Browse all documentation

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 /v1/trade/flows

GET /v1/trade/flows 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_get_flows 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"
Chapter 85 exports, United Kingdom and Germany
{
  "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

ParameterWhereTypeRequiredDefaultAllowed values and meaning
reporterquerystringNoEvery country held directlyReporting 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_not_covered. A reporter held by no source of its own is answered from other countries' reports and needs to be named.
partnerquerystringNoAll partnersPartners, ISO 3166-1 alpha-3 codes in capitals, as a comma list of up to 10.
hsquerystringNoNoneHS 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.
flowquerystringNoBoth flowsexport or import.
startquerystring, YYYY-MMNoEach reporter's newest monthFirst month, inclusive. From start to end is at most 12 months.
endquerystring, YYYY-MMNoEach reporter's newest monthLast month, inclusive. With only one of start and end, that month alone.
basisquerystringNoThe best source each reporter holdsown, third_party or partner_reported. Only this source answers. A source with no rows for the question answers 404 basis_not_available.
currencyquerystringNoEach reporter's own currency, named on each rowUSD. Converts each row with its month's average daily rate.
include_groupsquerybooleanNofalsetrue 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.
limitqueryintegerNo500From 1 to 1000. The most rows in one page.
cursorquerystringNoNoneThe next_cursor of the previous page, with every other parameter unchanged.

Response

The answer holds these fields.

FieldMeaning
scopegoods.
basesThe sources the rows of this answer come from, each own, third_party or partner_reported.
reportersThe reporters that have rows on this page, sorted. A later page can list more.
latest_periodThe newest month among the rows held directly. null when there are none.
noteRead this before using the figures. Set when a row is partner-reported, null otherwise.
fxWith currency=USD: the rate used for each month, with period, from_currency, to_currency, rate and days. null otherwise.
calculatedThe names of the fields Narwhal computed.
totalThe number of rows that match, over all pages.
next_cursorThe cursor of the next page. null on the last page.

Each item of rows is one reporter, month, flow, partner and chapter.

FieldMeaning
reporterISO 3166-1 alpha-3 code of the reporting country.
basisThe source of this row: own, third_party or partner_reported.
sourceThe publisher of this row.
currencyISO 4217 code of this row's value.
flowexport or import.
periodThe month, YYYY-MM.
period_typemonth.
period_start, period_endThe first and last day the row covers, YYYY-MM-DD.
partner, partner_label, partner_kind, unallocated_reasonAs on the partners route.
product_codeThe chapter when hs was sent. null for a partner total.
valueWhole units of currency, as a decimal string.
net_weight_kgNet 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"
Chapter 85 imports from China
{
  "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"
Canada, chapter 85
{
  "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_reported. 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_not_available 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_not_available, and an unavailable rate source answers 503 upstream_unavailable.

Paging

limit sets the most rows in one page, from 1 to 1000, and defaults to 500. 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. 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_id. 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.

StatusCodeWhen it happens
400invalid_queryNo 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_of or version was sent. Also when a partner-reported answer would need more than 30 reporter, partner and chapter combinations.
400invalid_cursorThe cursor is not one this request returned, or another parameter changed since.
400range_too_largeThe 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.
404country_not_coveredA named reporter is not in the coverage list (ATA is not in the trade coverage list.).
404basis_not_availablebasis names a source with no rows for the question, or every reporter named holds partner totals only and hs was sent.
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

Was this page helpful?