Trade by partner API reference
Read a country's exports and imports by partner country, one row for each partner, month and flow, with the publisher's own total beside the sum of the rows.
Overview
GET /
GET / returns one country's goods trade by partner: one row for each partner, month and flow. Without start and end the answer is the newest month held.
Use it to see who a country trades with and how much. For the same country by product use the products route, and for one product against every partner use the product route. To compare several countries in one call use the open query route.
Every answer names the source that produced it in basis and source, and carries the publisher's own total beside the sum of the rows in totals. With hs the totals are those of that product, and official_ is null. The MCP tool is trade_ and takes the same parameters.
Request
The three largest export partners of the United Kingdom in June 2026, and the real response:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"{
"country": "GBR",
"basis": "own",
"source": "HM Revenue & Customs",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "GBP",
"classification": "HS",
"edition": "2022",
"edition_basis": "inferred_from_year",
"valuation_basis": "not_stated",
"trade_system": "not_stated",
"partner_basis": "not_stated",
"trade_scope": "all_partners",
"latest_period": "2026-09",
"total_basis": "customs",
"totals": [
{
"period": "2026-06",
"flow": "export",
"official_total": "37649508686",
"sum_of_rows": "37649508686"
}
],
"fx": null,
"calculated": [
"sum_of_rows",
"rank"
],
"total": 3,
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "5316654916",
"net_weight_kg": "76287894",
"rank": 1,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "4735227787",
"net_weight_kg": "341314142",
"rank": 2,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}The page shows the first two of the three rows. basis is own, so HM Revenue & Customs answered, and official_ equals sum_. rank is set because top was sent, and calculated lists it.
Parameters
| Parameter | Where | Type | Required | Default | Allowed values and meaning |
|---|---|---|---|---|---|
country | path | string | Yes | None | ISO 3166-1 alpha-3 code of the reporting country, in capitals, such as GBR. A code that is not a country answers 400. A country with no figures answers 404 country_. |
partner | query | string | No | All partners | ISO 3166-1 alpha-3 code of one partner, in capitals. A code that is not a partner of the country answers 400 unknown_. |
flow | query | string | No | Both flows | export or import. |
start | query | string, YYYY-MM | No | The newest month held | First month, inclusive. With start and no end the answer runs to the newest month held. start after end answers 400. |
end | query | string, YYYY-MM | No | The newest month held | Last month, inclusive. With end alone the answer is the newest month held on or before it. |
hs | query | string | No | All products | Only trade in this product, as a code of 2, 4 or 6 digits (85, 8517, 851713): each partner's share of it. A code of another length answers 400. Thailand is held at 4 digits, so for Thailand a code of 6 digits answers 404 basis_. |
basis | query | string | No | The best source held | own, third_ or partner_. Asks for one source by name and skips the order. A source with nothing for the question answers 404 basis_. |
currency | query | string | No | The source's own currency | USD. Converts each month with its average daily rate. |
top | query | integer | No | All rows | From 1 to 1000. Keeps the N largest country rows of each month and flow, ranked by value with ties broken by partner code, and adds rank to each row. Group and unallocated rows are not ranked. Calculated. Covers at most 12 months. Not for partner-reported answers. |
share | query | boolean | No | false | true adds share to each row: its value over the sum of the country rows of the same month and flow, as a fraction of 1 with 6 decimals. Calculated. Covers at most 12 months. Not for partner-reported answers. |
ytd | query | boolean | No | false | true sums January to end (default: the newest month) from the stored months, and period_ is year_. Send end, not start: with start the request answers 400. A missing month answers 404 period_. Calculated. Not for partner-reported answers. |
change | query | boolean | No | false | true adds change to each row: the same month (or year to date) a year earlier, with the difference and the release status of both sides. A missing month a year earlier answers 404 period_. Calculated. Covers at most 12 months. Not for partner-reported answers. |
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. Everything that is the same for every row sits here once.
| Field | Meaning |
|---|---|
country | ISO 3166-1 alpha-3 code of the reporting country the answer is about. |
basis | The source that answered: own, third_ (UN Comtrade) or partner_. |
source | The publisher, for example HM Revenue & Customs, Eurostat Comext, UN Comtrade or Customs reports of other countries. |
reporters_ | With partner_: count and countries of the reporters whose reports were swapped into the answer. null for the other sources. |
note | Read this before using the figures. Set on partner-reported answers, null otherwise. |
coverage | full or partial. A partner-reported answer is partial. |
partner_ | all when every partner is listed, top_ when the publisher prints only its top partners and one rest row. null for partner-reported answers. |
scope | goods. |
currency | ISO 4217 code of every value in the answer. |
classification | HS, the Harmonized System. |
edition | The HS edition (2007, 2012, 2017 or 2022) when one edition covers every month asked. null when months differ, and each row names its own. |
edition_ | as_ when the publisher states the edition, inferred_ when Narwhal worked it out from the year. |
valuation_ | How the publisher values trade, such as FOB for exports and CIF for imports. not_ when it does not say. |
trade_ | general or special where the publisher says. not_ otherwise. |
partner_ | Whether partners are counted by origin, consignment or destination, as the publisher says. not_ otherwise. |
trade_ | What the figures cover, such as all_, extra_ or intra_. |
latest_ | The newest month Narwhal holds for this country and source. |
total_ | The basis of official_: customs, balance_ or eurostat_. null when the publisher gives no total. |
totals | One item for each month and flow: period, flow, official_ (the publisher's own goods total, null when none exists) and sum_ (the sum of every partner row of the month and flow except group rows, calculated). Without hs it holds the whole goods total of the month, also when partner limits the rows. With hs (and on the one-product route) it holds that product's total instead: sum_ is the sum of the rows of the answer over all pages (the named partner's, if one is given; top and paging do not cut it), and official_ is null, because the publisher prints no total for one product. |
fx | With currency=USD, and on partner-reported answers in more than one currency: the rate used for each month, with period, from_, to_, rate and days in the average. null otherwise. |
calculated | The names of the fields Narwhal computed, such as sum_, rank, share, value or official_. |
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 partner in one month and flow.
| Field | Meaning |
|---|---|
flow | export or import. |
period | The month, YYYY-MM. For a year to date, its last month. |
period_ | month or year_. |
period_ | The first and last day the row covers, YYYY-MM-DD. |
value | Whole units of currency, as a decimal string. |
net_ | Net weight in kilograms, as a decimal string, where the publisher gives it. null otherwise. |
rank | With top: the row's rank, 1 for the largest. null otherwise. |
share | With share: the row's fraction of the total, 6 decimals. null otherwise. |
change | With change: an object with previous_, previous_, absolute (value minus previous value), percent (in percent with 4 decimals, null when the earlier value was 0), release_ and previous_ (preliminary, revised, final or null when the publisher does not say). null when the row a year earlier does not exist or change was not asked for. |
partner | ISO 3166-1 alpha-3 code of the partner, a group code such as EUU, or empty for a line that has no country. |
partner_ | The publisher's own name for the partner. |
partner_ | country, group or unallocated. |
unallocated_ | For an unallocated row: not_, confidential, stores_, free_, other or rest. null otherwise. |
More examples
Both flows for one partner
Germany with China, January to June 2026, both flows:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"{
"country": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "EUR",
"classification": "HS",
"edition": "2022",
"edition_basis": "inferred_from_year",
"valuation_basis": "not_stated",
"trade_system": "not_stated",
"partner_basis": "not_stated",
"trade_scope": "all_partners",
"latest_period": "2026-09",
"total_basis": "eurostat_concept",
"totals": [
{
"period": "2026-01",
"flow": "export",
"official_total": "121792305000",
"sum_of_rows": "121792305000"
},
{
"period": "2026-01",
"flow": "import",
"official_total": "106754947046",
"sum_of_rows": "106754947046"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 12,
"rows": [
{
"flow": "export",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "5559611667",
"net_weight_kg": "355538457",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "import",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "8853410701",
"net_weight_kg": "1020758294",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}The page shows the first two of 12 rows and the first two of 12 totals items. Germany is answered from Eurostat Comext, in euros.
A product the country's own office does not give
Canada's own office gives partner totals only. A request for one product answers 404 and is free:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"{
"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; UN Comtrade is held as partner totals only, not by product; partner-reported answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}Sources
One source answers each request, the first that holds rows in this order: the country's own customs or statistics office (basis is own), the country's own filing with UN Comtrade (third_, partner totals only), then other countries' reports about it with the flows swapped (partner_). 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 then partner_, and partner_ reaches chapters (2 digits) only. basis asks for one source by name. The answer's basis, source and note fields say which source answered, and the sources are never mixed in one answer. A partner-reported answer is a different measurement from the country's own figures and is never an official figure. The partner list of a source can be short: when partner_ is top_ the publisher names its top partners and one rest row, and the rows still add up to the total.
Currency
Values are whole units of the currency named in currency, written as decimal strings. By default that is the currency the source publishes in, for example GBP for HM Revenue & Customs. currency=USD converts each month with the average of that month's daily exchange rates. The rate used for each month is listed in fx, and calculated names the converted fields. A month with no rate answers 404 rate_. If the rate source cannot answer, the request answers 503 upstream_. An answer that is already in USD comes back as it is.
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 | 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 | 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. |
Was this page helpful?