All APIs

Merchandise imports API

Official merchandise import totals across ten countries.

First request

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/trade/imports?period=2026-06" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Example response Illustrative response · not a live request

{
  "country": "USA",
  "period": "2026-06",
  "flow": "import",
  "value": "275000000000",
  "currency": "USD",
  "coverage": "merchandise",
  "partner": null,
  "product": null,
  "released_on": "2026-08-04"
}

Endpoints

GETMerchandise imports/v1/economics/{country}/trade/imports

country: One supported uppercase country code: AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP, and USA.
period: Omit it for the latest accepted complete release, or pass one exact period.
partner: Accepted by the contract, but filtered partner totals are not published in the current beta.
product: An HS product code. Supply it together with classification.
classification: The Harmonized System edition. Supply it together with product.

MCP · economics_get_trade_imports

API reference →

GETMerchandise imports history/v1/economics/{country}/trade/imports/observations

country: One supported uppercase country code: AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP, and USA.
start: Inclusive first observation period.
end: Inclusive last observation period.
limit: Maximum observations returned. Defaults to 100.
cursor: The next_cursor from the previous page.

MCP · economics_get_trade_imports_history

API reference →

History

cURL

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/trade/imports/observations?start=2026-06&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Example response Illustrative response · not a live request

{
  "observations": [
    {
      "country": "USA",
      "measure": "trade_imports",
      "value": "275000000000",
      "unit": "USD",
      "transformation": "",
      "period": "2026-06"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T16:00:00Z"
}

Sources and methodology

Primary sources

Every live stream comes from an official national publisher.

Read the methodology →

Explicit periods

Omit it for the latest accepted complete release, or pass one exact period.

REST and MCP

Use one API key for current and historical data through REST or MCP.

Coverage

View coverage →

AUS CAN DEU FRA GBR JPN MYS NLD SGP USA

Common questions

What does the response include?

Retrieve the merchandise-import total for one country and period.

Which periods can I request?

YYYY or YYYY-MM

What coverage is available?

Unfiltered national merchandise-import totals are public for AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP, and USA. Partner and product filters are accepted by the contract but return 404 until filtered totals are published.

Make your first request

Get a free API key →