Merchandise imports API

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

economics_get_trade_imports is available through REST and the economics_get_trade_imports MCP tool. Both return the same data shape and consume the same monthly quota.

Endpoint and request

REST endpoint

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

Example request

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

MCP uses tool economics_get_trade_imports with the corresponding arguments below.

REST sends product and classification as separate query parameters. MCP nests them in one product object:

MCP filtered-trade arguments

{
  "country": "USA",
  "period": "2026-06",
  "partner": "CAN",
  "product": {
    "classification": "HS2022",
    "code": "27"
  }
}

Parameters

The accepted period format for this operation is YYYY or YYYY-MM.

Name	Required	Type	Meaning
`country`	Yes	path · ISO alpha-3	One supported uppercase country code: AUS, CAN, DEU, FRA, GBR, JPN, MYS, SGP, and USA.
`period`	No	query · YYYY or YYYY-MM	Omit it for the latest accepted complete release, or pass one exact period.
`partner`	No	query · ISO alpha-3	Accepted by the contract, but filtered partner totals are not published in the current beta.
`product`	No	query · 2, 4, or 6 digits	An HS product code. Supply it together with classification.
`classification`	No	query · HSYYYY	The Harmonized System edition. Supply it together with product.

Response

Example response

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

Field	Type	Required	Meaning
`country`	string	Yes	The requested uppercase ISO alpha-3 country code.
`period`	string	Yes	The official observation period returned.
`flow`	"export" or "import"	Yes	The merchandise-trade direction fixed by the route.
`value`	decimal string	Yes	The monetary value for the selected direction.
`currency`	ISO 4217 string	Yes	The currency for the monetary value.
`coverage`	"merchandise"	Yes	Confirms that services trade is not included.
`partner`	ISO alpha-3 string or null	No	The requested partner filter when present. It can be null or omitted for the public unfiltered total.
`product`	object or null	No	The requested HS classification and product code when present. It can be null or omitted for the public unfiltered total.
`released_on`	date	Yes	The official publication date, not Narwhal's retrieval time.

Errors and quota

400 invalid_query — the country, period, or filter format is invalid.
401 invalid_api_key — the Bearer key is missing or rejected.
404 series_not_found — no complete approved publication matches the request.
429 quota_exhausted — the account has reached its monthly allowance.
503 economics_unavailable — Narwhal cannot safely serve an accepted publication.

Only a successful data response consumes quota. See all errors, headers, and retry rules.

Freshness

Omitting period returns Narwhal's latest stored accepted release. The API call reads Narwhal's database; it does not call the official publisher live.

released_on is the official publication date. Read how source checks, validation, stored releases, and failed checks work.

Current public-beta coverage

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

Indonesia, regional routes, Commodities, and FX are not part of the public beta.

Return to all Economics operations.