Browse all documentation

Trade in one product API reference

Read one country's exports and imports of one HS code with every partner, one row for each partner, month and flow, with the code's name.

Overview

GET /v1/trade/{country}/products/{hs}

GET /v1/trade/{country}/products/{hs} returns one country's trade in one HS code with every partner: one row for each partner, month and flow, and the code's name. hs is a code of 2, 4 or 6 digits.

Use it to see which partners buy or sell a product. It takes the same options as the partners route, and a partners request with hs answers the same figures.

A code that the HS edition does not have answers 404 hs_code_not_found. The MCP tool is trade_get_product and takes the same parameters.

Request

Heading 8517 (telephone sets and other apparatus for sending and receiving data) of the United Kingdom with the United States in June 2026, and the real response:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/8517?partner=USA&start=2026-06&end=2026-06"
United Kingdom, heading 8517, with the United States
{
  "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": "46135455"
    },
    {
      "period": "2026-06",
      "flow": "import",
      "official_total": null,
      "sum_of_rows": "89090099"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 2,
  "product_code": "8517",
  "product_level": 4,
  "product_label": "Telephone sets, incl. telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, incl. apparatus for communication in a wired or wireless network [such as a local or wide area network]; parts thereof (excl. than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528)",
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "46135455",
      "net_weight_kg": "74435",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "89090099",
      "net_weight_kg": "246068",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

There is one row for each flow. totals holds the total of heading 8517 with the United States, the sum of the two rows, and official_total is null because the publisher prints no total for one product.

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.
hspathstringYesNoneAn HS code of 2, 4 or 6 digits, such as 85, 8517 or 851713. Any other length answers 400. A code that has no name in the HS edition and no rows for the country answers 404 hs_code_not_found. Thailand is held at 4 digits, so for Thailand a code of 6 digits answers 404 basis_not_available.
partnerquerystringNoAll partnersISO 3166-1 alpha-3 code of one partner, 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.
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 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.
sharequerybooleanNofalsetrue 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.
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.
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 the fields of the partners route, which are listed on that page, and these three about the product. totals holds the total of that product, the sum of its rows over all pages, with official_total null.

FieldMeaning
product_codeThe HS code asked for.
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, such as the publisher's residual code 999999 of Chile, which answers with its rows.

Each item of rows is one partner in one month and flow, with the same fields as on the partners route.

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, as a decimal string, where the publisher gives it. null otherwise.
rankWith top: the row's rank, 1 for the largest. null otherwise.
shareWith share: the row's fraction of the total, 6 decimals. null otherwise.
changeWith change: an object with previous_period, previous_value, absolute (value minus previous value), percent (in percent with 4 decimals, null when the earlier value was 0), release_status and previous_release_status (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.
partnerISO 3166-1 alpha-3 code of the partner, a group code such as EUU, or empty for a line that has no country.
partner_labelThe publisher's own name for the partner.
partner_kindcountry, group or unallocated.
unallocated_reasonFor an unallocated row: not_specified, confidential, stores_bunkers, free_zone, other or rest. null otherwise.

More examples

A code the edition does not have

An HS code that has no name and no rows answers 404 and is free:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/999999?start=2026-06&end=2026-06&flow=export&limit=3"
United Kingdom, code 999999
{
  "type": "https://narwhalapi.com/problems/hs-code-not-found",
  "title": "HS code not found",
  "status": 404,
  "detail": "HS 2022 has no code 999999.",
  "code": "hs_code_not_found",
  "request_id": "16a6db4e-d5d6-45ee-954b-4512cf137e63"
}

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. Partner-reported answers reach chapters only, so a code of 4 or 6 digits answers 404 basis_not_available for a country whose own office gives partner totals only.

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 start=2026-13, a start after end, ytd sent with start, 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.
404hs_code_not_foundThe HS edition has no name for the code and the country holds no rows for it, for example the United Kingdom and code 999999 answer HS 2022 has no code 999999. A code with no name that the country's files do hold (the publisher's residual lines) answers 200 with product_label null.
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?