Browse all documentation

Trade by product API reference

Read a country's exports and imports by HS product at 2, 4 or 6 digits, one row for each code, month and flow, with each code's name.

Overview

GET /v1/trade/{country}/products

GET /v1/trade/{country}/products returns one country's goods trade by product: one row for each HS code, month and flow, with the code's name. level picks the depth: 2 for chapters (the default), 4 for headings and 6 for subheadings. Without start and end the answer is the newest month held.

partner limits the answer to one partner and hs to the codes that start with those digits. Use it to see what a country sells and buys. For one product against every partner use the product route.

Where a country's own office gives partner totals only (Canada, Mexico and Australia), the products route answers chapters from other countries' reports, labelled partner_reported, and answers 404 basis_not_available for headings and subheadings. The MCP tool is trade_get_products and takes the same parameters.

Request

The three largest export chapters of the United Kingdom in June 2026 with their share, and the real response:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?start=2026-06&end=2026-06&flow=export&top=3&share=true"
United Kingdom, three largest export chapters
{
  "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",
    "share"
  ],
  "total": 3,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7115661421",
      "net_weight_kg": "195511199",
      "rank": 1,
      "share": "0.188997",
      "change": null,
      "product_code": "84",
      "product_level": 2,
      "product_label": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES; PARTS THEREOF",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7044982137",
      "net_weight_kg": "1706268",
      "rank": 2,
      "share": "0.187120",
      "change": null,
      "product_code": "71",
      "product_level": 2,
      "product_label": "NATURAL OR CULTURED PEARLS, PRECIOUS OR SEMI-PRECIOUS STONES, PRECIOUS METALS, METALS CLAD WITH PRECIOUS METAL, AND ARTICLES THEREOF; IMITATION JEWELLERY; COIN",
      "edition": "2022"
    }
  ],
  "next_cursor": null
}

The page shows the first two of the three rows. share is a fraction of 1: chapter 84 is 0.189134 of the month's exports. partner is null because the rows are not limited to one partner.

Parameters

ParameterWhereTypeRequiredDefaultAllowed values and meaning
countrypathstringYesNoneISO 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_not_covered.
levelqueryintegerNo22 (chapters), 4 (headings) or 6 (subheadings). Any other value answers 400. Thailand is held at 4 digits, so for Thailand 6 answers 404 basis_not_available.
partnerquerystringNoAll partnersOnly trade with this partner (ISO 3166-1 alpha-3, in capitals). A code that is not a partner of the country answers 400 unknown_partner.
flowquerystringNoBoth flowsexport or import.
startquerystring, YYYY-MMNoThe newest month heldFirst month, inclusive. With start and no end the answer runs to the newest month held. start after end answers 400.
endquerystring, YYYY-MMNoThe newest month heldLast month, inclusive. With end alone the answer is the newest month held on or before it.
hsquerystring, 1 to 6 digitsNoAll codesOnly codes that start with these digits. Longer than level answers 400.
basisquerystringNoThe best source heldown, third_party or partner_reported. Asks for one source by name and skips the order. A source with nothing for the question answers 404 basis_not_available.
currencyquerystringNoThe source's own currencyUSD. Converts each month with its average daily rate.
topqueryintegerNoAll rowsFrom 1 to 1000. Keeps the N largest product rows of each month and flow, ranked by value with ties broken by product code, and adds rank to each row. Calculated. Covers at most 12 months. Not for partner-reported answers.
sharequerybooleanNofalsetrue adds share to each row: its value over the sum of all product 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.
ytdquerybooleanNofalsetrue sums January to end (default: the newest month) from the stored months, and period_type is year_to_date. Send end, not start: with start the request answers 400. A missing month answers 404 period_not_published. Calculated. Not for partner-reported answers.
changequerybooleanNofalsetrue 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_not_published. Calculated. Covers at most 12 months. Not for partner-reported answers.
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 the fields of the partners route, which are listed on that page, with one more about the partner filter.

FieldMeaning
countryISO 3166-1 alpha-3 code of the reporting country the answer is about.
partnerThe partner the rows are limited to, null when partner was not sent.
basisThe source that answered: own, third_party (UN Comtrade) or partner_reported.
sourceThe publisher, for example HM Revenue & Customs, Eurostat Comext, UN Comtrade or Customs reports of other countries.
reporters_includedWith partner_reported: count and countries of the reporters whose reports were swapped into the answer. null for the other sources.
noteRead this before using the figures. Set on partner-reported answers, null otherwise.
coveragefull or partial. A partner-reported answer is partial.
partner_coverageall when every partner is listed, top_n when the publisher prints only its top partners and one rest row. null for partner-reported answers.
scopegoods.
currencyISO 4217 code of every value in the answer.
classificationHS, the Harmonized System.
editionThe 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_basisas_published when the publisher states the edition, inferred_from_year when Narwhal worked it out from the year.
valuation_basisHow the publisher values trade, such as FOB for exports and CIF for imports. not_stated when it does not say.
trade_systemgeneral or special where the publisher says. not_stated otherwise.
partner_basisWhether partners are counted by origin, consignment or destination, as the publisher says. not_stated otherwise.
trade_scopeWhat the figures cover, such as all_partners, extra_union_only or intra_union_other_method.
latest_periodThe newest month Narwhal holds for this country and source.
total_basisThe basis of official_total: customs, balance_of_payments or eurostat_concept. null when the publisher gives no total.
totalsOne item for each month and flow: period, flow, official_total (the publisher's own goods total, null when none exists) and sum_of_rows (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_of_rows 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_total is null, because the publisher prints no total for one product.
fxWith currency=USD, and on partner-reported answers in more than one currency: the rate used for each month, with period, from_currency, to_currency, rate and days in the average. null otherwise.
calculatedThe names of the fields Narwhal computed, such as sum_of_rows, rank, share, value or official_total.
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 HS code in one month and flow.

FieldMeaning
flowexport or import.
periodThe month, YYYY-MM. For a year to date, its last month.
period_typemonth or year_to_date.
period_start, period_endThe first and last day the row covers, YYYY-MM-DD.
valueWhole units of currency, as a decimal string.
net_weight_kgNet weight in kilograms where the publisher gives it. null otherwise.
rank, share, changeAs on the partners route: set with top, share and change, null otherwise.
product_codeThe HS code, 2, 4 or 6 digits. A publisher's own line that is not an HS product keeps the publisher's code, such as 00 for ship supplies and private shipments.
product_level2 for a chapter, 4 for a heading, 6 for a subheading.
product_labelThe code's name. null for a line that is not an HS product.
editionThe HS edition of the month's source. null when reporters use different ones.

More examples

Subheadings of one heading

The six-digit codes under heading 8517 for United Kingdom exports, first page of five:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?level=6&hs=8517&start=2026-06&end=2026-06&flow=export&limit=5"
United Kingdom, subheadings of 8517
{
  "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": null,
      "sum_of_rows": "427312411"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 9,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "2578425",
      "net_weight_kg": "12393",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851711",
      "product_level": 6,
      "product_label": "Line telephone sets with cordless handsets",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "105530961",
      "net_weight_kg": "115108",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851713",
      "product_level": 6,
      "product_label": "Smartphones for wireless networks",
      "edition": "2022"
    }
  ],
  "next_cursor": "eyJiIjoiY2hhbmdlPUZhbHNlfGNvdW50cnk9R0JSfGVuZD0yMDI2LTA2fGZsb3c9ZXhwb3J0fGhzPTg1MTd8bGV2ZWw9NnxzaGFyZT1GYWxzZXxzdGFydD0yMDI2LTA2fHl0ZD1GYWxzZSIsIm8iOjV9"
}

The page shows the first two of the five rows. total is 9, so next_cursor is set. totals holds the sum of the nine subheadings, and official_total is null.

Headings of a country that gives partner totals only

Canada's own office does not give products. A request for headings answers 404 and is free:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/products?level=4&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
Canada, headings under 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; UN Comtrade is held as partner totals only, not by product; partner-reported products are held at chapter level only (level=2). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "5dd0f449-8c1e-4354-9af6-d8a76a5eefdd"
}

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_party, partner totals only), then other countries' reports about it with the flows swapped (partner_reported). 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_reported, and partner_reported 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 publisher's own lines that are not HS products, such as ship supplies and private shipments, come back under the publisher's code (00 at chapter level, 999999 at subheading level) with product_label null. The HS code routes (/v1/trade/hs-codes) do not know these codes and answer 404 for them. The one-product route (/v1/trade/{country}/products/{hs}) answers them with their rows and product_label null.

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_not_available. If the rate source cannot answer, the request answers 503 upstream_unavailable. 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_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_queryA parameter is missing, malformed or outside its allowed values: for example level=3, start=2026-13, a start after end, ytd sent with start, an hs longer than level, 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.
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

Was this page helpful?