Open trade query API reference
Ask any reporters, partners and HS chapters in one call, such as the top exporters of a product or one country against another.
Overview
GET /
GET / returns exports and imports for any reporters, partners and HS chapters you name, in one call. Each of reporter, partner and hs takes a comma list of up to 10. One row is one reporter, month, flow, partner and chapter.
Use it for questions that cross countries or products: who exports a chapter, how one country trades with another, or two countries side by side. Name at least one of reporter, partner and hs. Left out, reporter means every country Narwhal holds directly, from its own office or from UN Comtrade.
Each row names its own basis, source and currency, because reporters can answer from different sources. Rows from different sources are never summed. The window is at most 12 months, and without start and end each reporter answers with its newest month. Without hs the rows are partner totals, and with hs they are chapter rows. The MCP tool is trade_ and takes the same parameters.
Request
Exports of chapter 85 (electrical machinery) of the United Kingdom and Germany in June 2026, first page of five:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"DEU"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 396,
"rows": [
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "ABW",
"partner_label": "Aruba",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "108666",
"net_weight_kg": "731"
},
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "AFG",
"partner_label": "Afghanistan",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "153236",
"net_weight_kg": "2893"
}
],
"next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}The page shows the first two of the five rows. total is 396, so more pages follow. Page 1 holds rows of Germany only, and reporters lists the reporters on the page, so it shows DEU alone even though two were asked.
Parameters
| Parameter | Where | Type | Required | Default | Allowed values and meaning |
|---|---|---|---|---|---|
reporter | query | string | No | Every country held directly | Reporting countries, ISO 3166-1 alpha-3 codes in capitals, as a comma list of up to 10, such as GBR,DEU. A code that is not a country answers 400 and names the code. A country outside the coverage list answers 404 country_. A reporter held by no source of its own is answered from other countries' reports and needs to be named. |
partner | query | string | No | All partners | Partners, ISO 3166-1 alpha-3 codes in capitals, as a comma list of up to 10. |
hs | query | string | No | None | HS chapters, 2 digits, as a comma list of up to 10, such as 85,87. Rows are then chapter rows. Left out, rows are partner totals. Only chapters are held for the open query. |
flow | query | string | No | Both flows | export or import. |
start | query | string, YYYY-MM | No | Each reporter's newest month | First month, inclusive. From start to end is at most 12 months. |
end | query | string, YYYY-MM | No | Each reporter's newest month | Last month, inclusive. With only one of start and end, that month alone. |
basis | query | string | No | The best source each reporter holds | own, third_ or partner_. Only this source answers. A source with no rows for the question answers 404 basis_. |
currency | query | string | No | Each reporter's own currency, named on each row | USD. Converts each row with its month's average daily rate. |
include_ | query | boolean | No | false | true also returns the group rows the publisher prints, such as the EU or ASEAN. A group row is never part of a sum, a rank or a share. |
limit | query | integer | No | 500 | From 1 to 1000. The most rows in one page. |
cursor | query | string | No | None | The next_ of the previous page, with every other parameter unchanged. |
Response
The answer holds these fields.
| Field | Meaning |
|---|---|
scope | goods. |
bases | The sources the rows of this answer come from, each own, third_ or partner_. |
reporters | The reporters that have rows on this page, sorted. A later page can list more. |
latest_ | The newest month among the rows held directly. null when there are none. |
note | Read this before using the figures. Set when a row is partner-reported, null otherwise. |
fx | With currency=USD: the rate used for each month, with period, from_, to_, rate and days. null otherwise. |
calculated | The names of the fields Narwhal computed. |
total | The number of rows that match, over all pages. |
next_ | The cursor of the next page. null on the last page. |
Each item of rows is one reporter, month, flow, partner and chapter.
| Field | Meaning |
|---|---|
reporter | ISO 3166-1 alpha-3 code of the reporting country. |
basis | The source of this row: own, third_ or partner_. |
source | The publisher of this row. |
currency | ISO 4217 code of this row's value. |
flow | export or import. |
period | The month, YYYY-MM. |
period_ | month. |
period_ | The first and last day the row covers, YYYY-MM-DD. |
partner, partner_ | As on the partners route. |
product_ | The chapter when hs was sent. null for a partner total. |
value | Whole units of currency, as a decimal string. |
net_ | Net weight in kilograms where the publisher gives it. null otherwise. |
More examples
Reporters with partner totals only are skipped
US imports from China in chapter 85, with Canada and Mexico named too. Their own offices give partner totals only, so only the United States answers:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"USA"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 1,
"rows": [
{
"reporter": "USA",
"basis": "own",
"source": "US Census Bureau",
"currency": "USD",
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "5834371932",
"net_weight_kg": null
}
],
"next_cursor": null
}Only reporters with partner totals
When every named reporter gives partner totals only and hs is sent, the call answers 404 and is free:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"{
"type": "https://narwhalapi.com/problems/basis-not-available",
"title": "Basis not available",
"status": 404,
"detail": "Narwhal holds CAN's own partner totals only, not its products. See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}Sources
Each reporter answers from the best source it is held in: its own office, then its UN Comtrade filing (partner totals only), and a reporter held by neither is answered from other countries' reports, labelled partner_. By chapter UN Comtrade holds nothing. basis forces one source for every reporter. A reporter whose own office gives partner totals only has no chapter rows: it is skipped when other reporters answer, and the call answers 404 basis_ when none can.
Currency
Each row is in its reporter's own currency, named in the row's currency. currency=USD converts every row with its month's average daily rate and lists the rates in fx. A month with no rate answers 404 rate_, and an unavailable rate source answers 503 upstream_.
Paging
limit sets the most rows in one page, from 1 to 1000, and defaults to 500. 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. The MCP tool returns at most 200 rows in one result.
Price
A request that returns at least one row is one call, at $2 per 1,000 calls. Every page of a long answer is one call, whatever limit is. An answer with no rows is free, and so is every error.
Errors
These errors use the shared problem shape with a request_. A missing or invalid key (401), a balance below the price of the call (402) and too many requests a minute (429) are the account errors every route shares: see Errors and credits.
| Status | Code | When it happens |
|---|---|---|
400 | invalid_query | No reporter, partner or hs was named (an open query with none is the whole store), end is before start, the window is more than 12 months, a list holds more than 10 items, a reporter is not a country, a parameter is outside its allowed values, or as_ or version was sent. Also when a partner-reported answer would need more than 30 reporter, partner and chapter combinations. |
400 | invalid_cursor | The cursor is not one this request returned, or another parameter changed since. |
400 | range_too_large | The answer would hold more than 200,000 rows, or chapter rows without a partner cover more than 36 reporter-months. Name fewer reporters, partners or chapters, or a shorter window. |
404 | country_not_covered | A named reporter is not in the coverage list (ATA is not in the trade coverage list.). |
404 | basis_not_available | basis names a source with no rows for the question, or every reporter named holds partner totals only and hs was sent. |
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. |
Was this page helpful?