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 /, 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
| Route | MCP tool | What it answers |
|---|---|---|
GET / | trade_ | One country's exports and imports by partner. |
GET / | trade_ | One country's exports and imports by HS product, at 2, 4 or 6 digits. |
GET / | trade_ | One country's trade in one HS code with every partner. |
GET / | trade_ | An open query over several reporters, partners and chapters. |
GET / | trade_ | Which source answers for each country, and the months held. Free. |
GET / | trade_ | Search or list HS codes by name, level or parent. |
GET / | trade_ | One 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.
basis | Source | What it is | Reaches |
|---|---|---|---|
own | The country's own customs or statistics office | The 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_ | UN Comtrade | The country's own monthly filing with the United Nations, served with the source named. | Partner totals only |
partner_ | Customs reports of other countries | What 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_. A partner-reported answer has no official total, takes no top, share, ytd or change, and covers at most 12 months. GET / shows answers_, 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 /. When more rows match, next_ 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_. 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_. Each route page lists the errors it can return. These are all of them.
| Status | Code | When it happens |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | A missing or invalid key, a balance below the price of the call, or too many requests a minute. See Errors and credits. |
400 | invalid_query | A parameter is missing, malformed or outside its allowed values: for example start=2026-13, a start after end, ytd sent with start, or as_ or version sent (these routes serve what is held now). Also when top, share, ytd or change is asked of a partner-reported answer. |
400 | invalid_cursor | The cursor is not one this request returned, or another parameter changed since. |
400 | unknown_partner | partner is not a partner of the country in the months asked, for example ZZZ is not a partner of GBR. |
400 | range_too_large | top, 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_. |
404 | hs_code_not_found | The HS edition has no such code. |
404 | country_not_covered | Narwhal holds no trade rows for the country on any source. |
404 | period_not_published | The month asked is not held (No trade rows for 2026-10.), or a month that ytd or change needs is missing. |
404 | basis_not_available | The 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. |
404 | rate_not_available | currency=USD was asked and a month has no exchange rate. |
503 | upstream_unavailable | The exchange rate source cannot answer. It affects currency=USD and partner-reported answers that need a conversion. Try again shortly. |
503 | trade_data_unavailable | The product files cannot be read just now. Try again shortly. |
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_ flowsWas this page helpful?