Browse all documentation

Trade API reference

Read goods trade by partner country and by HS product, month by month, from the customs or statistics office of the country where Narwhal holds it, and from UN Comtrade or other countries' reports for the rest.

Overview

The Trade API returns goods trade by partner country and by product, one month at a time. A row is one flow, export or import, in one month, with a partner or a product and a value in whole units of a currency. Products follow the Harmonized System (HS) at 2, 4 and 6 digits. History starts in January 2010 where the source publishes it. The API covers goods only.

The figures come from the customs or statistics office of the reporting country where Narwhal holds it, and from UN Comtrade or other countries' reports for the rest of the 181 countries in the coverage list. Every answer says which source produced it. Which countries answer from which source is on the Trade countries page.

Seven routes answer, all under /v1/trade, and each is also an MCP tool with the same parameters and the same answer. Each request takes the key in the Authorization: Bearer header, as in the rest of Narwhal.

Routes

RouteMCP toolWhat it answers
GET /v1/trade/{country}/partnerstrade_get_partnersOne country's exports and imports by partner.
GET /v1/trade/{country}/productstrade_get_productsOne country's exports and imports by HS product, at 2, 4 or 6 digits.
GET /v1/trade/{country}/products/{hs}trade_get_productOne country's trade in one HS code with every partner.
GET /v1/trade/flowstrade_get_flowsAn open query over several reporters, partners and chapters.
GET /v1/trade/coveragetrade_get_coverageWhich source answers for each country, and the months held. Free.
GET /v1/trade/hs-codestrade_list_hs_codesSearch or list HS codes by name, level or parent.
GET /v1/trade/hs-codes/{code}trade_get_hs_codeOne HS code with its parent and children.

Each route has its own page with every parameter, a working request with its real response, and every error.

Sources

Each answer comes from one source, named in basis and source. A request without basis takes the first source in this order that holds rows. Sources are never mixed in one answer, and basis asks for one by name.

basisSourceWhat it isReaches
ownThe country's own customs or statistics officeThe office's own figures, in its own currency, as published.Partners, and products at 2, 4 and 6 digits where the office gives them
third_partyUN ComtradeThe country's own monthly filing with the United Nations, served with the source named.Partner totals only
partner_reportedCustoms reports of other countriesWhat other countries report about the country, with the flows swapped: their imports from it are its exports. A different measurement, never an official figure.Partners, and products at 2 digits

Other countries' reports would come before UN Comtrade only when at least 200 reporters have rows about the country, which is more than Narwhal holds, so they come last. By product, UN Comtrade holds nothing, so the order is own and then partner_reported. A partner-reported answer has no official total, takes no top, share, ytd or change, and covers at most 12 months. GET /v1/trade/coverage shows answers_with, the source that answers each country today.

Which country answers from which source: Trade countries.

Currency

Values are whole units of the currency in currency, as decimal strings. By default that is the currency the source publishes in. currency=USD converts each month with the average of that month's daily exchange rates, lists the rate used for each month in fx, and names the converted fields in calculated. The open query route names the currency on each row, because reporters publish in different currencies.

Paging

limit sets the most rows in one page, from 1 to 1000. It defaults to 500 on the partners, products, one product and open query routes and to 100 on GET /v1/trade/hs-codes. When more rows match, next_cursor holds the cursor of the next page: send it as cursor with every other parameter unchanged. A cursor from a different request answers 400 invalid_cursor. total counts the matching rows over all pages. An MCP tool returns at most 200 rows in one result.

Price

Trade calls cost $2 per 1,000 calls. A request that returns at least one row is one call, and every page of a long answer is one call. An answer with no rows is free, every error is free, and the coverage route is free. See pricing for credit and top-ups.

Errors

Errors use the shared problem shape with a request_id. Each route page lists the errors it can return. These are all of them.

StatusCodeWhen it happens
401, 402, 429unauthorized, insufficient_credits, rate_limitedA missing or invalid key, a balance below the price of the call, or too many requests a minute. See Errors and credits.
400invalid_queryA parameter is missing, malformed or outside its allowed values: for example start=2026-13, a start after end, ytd sent with start, or as_of or version sent (these routes serve what is held now). Also when top, share, ytd or change is asked of a partner-reported answer.
400invalid_cursorThe cursor is not one this request returned, or another parameter changed since.
400unknown_partnerpartner is not a partner of the country in the months asked, for example ZZZ is not a partner of GBR.
400range_too_largetop, share, ytd or change cover more than 12 months, a partner-reported answer covers more than 12 months, or a products answer, at any level (2, 4 or 6 digits), covers more than 12 months held without hs or partner. The open query refuses a window over 12 months as invalid_query.
404hs_code_not_foundThe HS edition has no such code.
404country_not_coveredNarwhal holds no trade rows for the country on any source.
404period_not_publishedThe month asked is not held (No trade rows for 2026-10.), or a month that ytd or change needs is missing.
404basis_not_availableThe source asked for, or every source in the order, holds nothing for the question. The detail names why: for example that the country's own office gives partner totals only, not products, or that partner-reported answers reach chapters (2 digits) only, or that Thailand's own office is held at 4 digits and was asked for 6. See the coverage route.
404rate_not_availablecurrency=USD was asked and a month has no exchange rate.
503upstream_unavailableThe exchange rate source cannot answer. It affects currency=USD and partner-reported answers that need a conversion. Try again shortly.
503trade_data_unavailableThe product files cannot be read just now. Try again shortly.

Errors and credits · Trade API reference · Trade countries

MCP tools

Each route is an MCP tool of its own, with the same parameters and the same answer. An MCP tool returns at most 200 rows in one result, so page with cursor. The tools are:

trade_list_hs_codestrade_get_hs_codetrade_get_coveragetrade_get_partnerstrade_get_productstrade_get_producttrade_get_flows

Was this page helpful?