Browse all documentation

Trade coverage route API reference

Read which source answers the trade routes for each country, what is held, and from which month to which.

Overview

GET /v1/trade/coverage

GET /v1/trade/coverage returns one row for each country: who answers the partners route and the products route, the source that answers today, every source held, and the months held. It is the live answer to the question the Trade countries page answers in general.

Call it before you build on a country. answers_with is the source a request without basis is answered from today, and tiers_held lists every value of basis that has rows. Send country for one row, or leave it out for every country. The call is free. The MCP tool is trade_get_coverage and takes the same parameter.

Request

The coverage of the United Kingdom, and the real response:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/coverage?country=GBR"
United Kingdom
{
  "countries": [
    {
      "country": "GBR",
      "partners_tier": "own",
      "partner_coverage": "all",
      "products_tier": "own",
      "answers_with": "own",
      "tiers_held": [
        "own",
        "partner_reported"
      ],
      "first_period": "2010-01",
      "latest_period": "2026-09",
      "comtrade_latest_period": "2026-08",
      "third_party_latest_period": null,
      "comtrade_periods": 200,
      "comtrade_latest_year": 2025,
      "has_headline": true,
      "has_services": true,
      "has_tariff_book": true
    }
  ]
}

The United Kingdom's own office answers (answers_with is own) and holds products (products_tier is own). first_period and latest_period are the months held from that office.

Parameters

ParameterWhereTypeRequiredDefaultAllowed values and meaning
countryquerystringNoEvery countryOne ISO 3166-1 alpha-3 code in capitals, or EMU for the euro area. Left out, the answer has one row for each country. A code that is not a country answers 400, and a country with no row answers 404.

Response

The answer has one field, countries, a list. Each item has these fields.

FieldMeaning
countryThe country, or EMU for the euro area.
partners_tierWho answers the partners route from what Narwhal holds directly: own, the country's own customs or statistics office, or partner_reported, other countries' reports with the flows swapped, when Narwhal holds no figures of the country's own office.
partner_coverageall when every partner is listed, top_n when the publisher prints only its top partners and one rest row. null when partners_tier is partner_reported.
products_tierWho answers the products route: own, or partner_reported when the country has no product files of its own. UN Comtrade holds partner totals only, so it never answers by product.
answers_withThe source the partners and products routes answer from today, in this order: the country's own office (own), its UN Comtrade filing (third_party), other countries' reports (partner_reported, never an official figure). 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 chapter UN Comtrade holds nothing, so partner_reported answers. null while Narwhal holds nothing for the country.
tiers_heldEvery source that has rows now: the values of basis that answer for this country.
first_periodThe first month Narwhal holds from the country's own office. null if none.
latest_periodThe latest month Narwhal holds from the country's own office. null if none.
comtrade_latest_periodThe latest month the country has filed with UN Comtrade. null if none.
third_party_latest_periodThe latest month Narwhal holds from UN Comtrade for the country. null if none.
comtrade_periodsThe number of months the country has filed with UN Comtrade.
comtrade_latest_yearThe latest year the country has filed with UN Comtrade.
has_headlinetrue when the country publishes a monthly headline total of goods trade.
has_servicestrue when the country publishes services trade.
has_tariff_booktrue when a national tariff book is available.

More examples

A country whose own office gives partner totals only

Canada, whose own office gives partner totals only:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/coverage?country=CAN"
Canada
{
  "countries": [
    {
      "country": "CAN",
      "partners_tier": "own",
      "partner_coverage": "top_n",
      "products_tier": "partner_reported",
      "answers_with": "own",
      "tiers_held": [
        "own",
        "partner_reported"
      ],
      "first_period": "2010-01",
      "latest_period": "2026-09",
      "comtrade_latest_period": "2026-08",
      "third_party_latest_period": null,
      "comtrade_periods": 200,
      "comtrade_latest_year": 2025,
      "has_headline": true,
      "has_services": true,
      "has_tariff_book": true
    }
  ]
}

partners_tier is own and products_tier is partner_reported: Canada's partners come from Statistics Canada, and its products by chapter come from other countries' reports.

A country that is not covered

A real country code with no figures answers 404 and is free:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/coverage?country=ATA"
Antarctica
{
  "type": "https://narwhalapi.com/problems/country-not-covered",
  "title": "Country not covered",
  "status": 404,
  "detail": "ATA is not in the trade coverage list.",
  "code": "country_not_covered",
  "request_id": "c16523b6-7d27-4e1b-a2c3-f7e2acead523"
}

Sources

The route reports the sources. It does not choose one. See the Trade countries page for what each source is and when it answers.

Currency

The route returns no values, so no currency applies.

Paging

The route has no paging. A request without country returns every country in one answer.

Price

This route is free. No call is charged, and an account still needs its key.

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_querycountry is not a country code.
404country_not_coveredNarwhal holds no trade rows for the country on any source.

Errors and credits · Trade API reference · Trade countries

Was this page helpful?