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 /
GET / 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_ is the source a request without basis is answered from today, and tiers_ 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_ 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"{
"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_ is own) and holds products (products_ is own). first_ and latest_ are the months held from that office.
Parameters
| Parameter | Where | Type | Required | Default | Allowed values and meaning |
|---|---|---|---|---|---|
country | query | string | No | Every country | One 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.
| Field | Meaning |
|---|---|
country | The country, or EMU for the euro area. |
partners_ | Who answers the partners route from what Narwhal holds directly: own, the country's own customs or statistics office, or partner_, other countries' reports with the flows swapped, when Narwhal holds no figures of the country's own office. |
partner_ | all when every partner is listed, top_ when the publisher prints only its top partners and one rest row. null when partners_ is partner_. |
products_ | Who answers the products route: own, or partner_ when the country has no product files of its own. UN Comtrade holds partner totals only, so it never answers by product. |
answers_ | The source the partners and products routes answer from today, in this order: the country's own office (own), its UN Comtrade filing (third_), other countries' reports (partner_, 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_ answers. null while Narwhal holds nothing for the country. |
tiers_ | Every source that has rows now: the values of basis that answer for this country. |
first_ | The first month Narwhal holds from the country's own office. null if none. |
latest_ | The latest month Narwhal holds from the country's own office. null if none. |
comtrade_ | The latest month the country has filed with UN Comtrade. null if none. |
third_ | The latest month Narwhal holds from UN Comtrade for the country. null if none. |
comtrade_ | The number of months the country has filed with UN Comtrade. |
comtrade_ | The latest year the country has filed with UN Comtrade. |
has_ | true when the country publishes a monthly headline total of goods trade. |
has_ | true when the country publishes services trade. |
has_ | true 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"{
"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_ is own and products_ is partner_: 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"{
"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_. 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 | country is not a country code. |
404 | country_not_covered | Narwhal holds no trade rows for the country on any source. |
Was this page helpful?