贸易覆盖范围路由 API 参考
读取各国的贸易路由由哪个来源提供数据、存有什么数据,以及起止月份。
概览
GET /
GET / 为每个国家返回一行:谁为伙伴国路由和产品路由提供数据、目前提供数据的来源、所有已存的来源,以及已存的月份。贸易国家页面对此作一般性说明,而它给出实时的答案。
在基于某个国家构建之前先调用它。answers_ 是不带 basis 的请求目前使用的来源,tiers_ 列出所有有数据行的 basis 值。发送 country 得到一行,省略则得到每个国家。该调用免费。MCP 工具是 trade_,参数相同。
请求
英国的覆盖范围,以及真实响应:
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
}
]
}英国的本国机构提供数据(answers_ 为 own),并存有产品数据(products_ 为 own)。first_ 和 latest_ 是来自该机构的已存月份。
参数
| 参数 | 位置 | 类型 | 必填 | 默认值 | 允许的取值及含义 |
|---|---|---|---|---|---|
country | 查询参数 | 字符串 | 否 | 每个国家 | 一个 ISO 3166-1 alpha-3 代码,大写,或表示欧元区的 EMU。省略时,响应为每个国家一行。不是国家的代码返回 400,没有对应行的国家返回 404。 |
响应
响应只有一个字段 countries,是一个列表。每一项包含以下字段。
| 字段 | 含义 |
|---|---|
country | 国家,或表示欧元区的 EMU。 |
partners_ | 谁根据 Narwhal 直接存有的数据为伙伴国路由提供数据:own,即该国自己的海关或统计机构;或 partner_,即 Narwhal 没有该国本国机构的数据时,使用流向互换后的其他国家的报告。 |
partner_ | 列出所有伙伴国时为 all,发布机构只列出其主要伙伴国和一个“其余”行时为 top_。partners_ 为 partner_ 时为 null。 |
products_ | 谁为产品路由提供数据:own,或该国没有自己的产品文件时的 partner_。UN Comtrade 只有伙伴国总额,因此从不按产品提供数据。 |
answers_ | 目前伙伴国路由和产品路由所用的来源,按以下顺序:该国的本国机构(own)、其向 UN Comtrade 的申报(third_)、其他国家的报告(partner_,绝不是官方数据)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按章划分时 UN Comtrade 没有数据,所以由 partner_ 提供数据。Narwhal 没有该国任何数据时为 null。 |
tiers_ | 目前有数据行的每个来源:可为该国提供数据的 basis 值。 |
first_ | Narwhal 从该国本国机构存有的第一个月份。没有时为 null。 |
latest_ | Narwhal 从该国本国机构存有的最新月份。没有时为 null。 |
comtrade_ | 该国向 UN Comtrade 申报过的最新月份。没有时为 null。 |
third_ | Narwhal 从 UN Comtrade 存有的该国的最新月份。没有时为 null。 |
comtrade_ | 该国向 UN Comtrade 申报过的月份数。 |
comtrade_ | 该国向 UN Comtrade 申报过的最新年份。 |
has_ | 该国发布货物贸易月度总额时为 true。 |
has_ | 该国发布服务贸易数据时为 true。 |
has_ | 有全国关税税则可用时为 true。 |
更多示例
本国机构只提供伙伴国总额的国家
加拿大,其本国机构只提供伙伴国总额:
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_ 为 own,products_ 为 partner_:加拿大的伙伴国数据来自加拿大统计局,其按章划分的产品数据来自其他国家的报告。
未覆盖的国家
一个真实的国家代码但没有数据,返回 404,且免费:
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"
}来源
该路由报告来源,但不选择来源。各来源是什么以及何时提供数据,见贸易国家页面。
币种
该路由不返回数值,因此不适用货币。
分页
该路由没有分页。不带 country 的请求在一个响应中返回每个国家。
价格
该路由免费。不计任何调用,账户仍需要其密钥。
错误
这些错误采用通用的错误响应格式,并带有 request_。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。
| 状态 | 代码 | 触发时机 |
|---|---|---|
400 | invalid_query | country 不是国家代码。 |
404 | country_not_covered | Narwhal 在任何来源中都没有该国的贸易数据行。 |
此页面对你有帮助吗?