浏览全部文档

贸易覆盖范围路由 API 参考

读取各国的贸易路由由哪个来源提供数据、存有什么数据,以及起止月份。

概览

GET /v1/trade/coverage

GET /v1/trade/coverage 为每个国家返回一行:谁为伙伴国路由和产品路由提供数据、目前提供数据的来源、所有已存的来源,以及已存的月份。贸易国家页面对此作一般性说明,而它给出实时的答案。

在基于某个国家构建之前先调用它。answers_with 是不带 basis 的请求目前使用的来源,tiers_held 列出所有有数据行的 basis 值。发送 country 得到一行,省略则得到每个国家。该调用免费。MCP 工具是 trade_get_coverage,参数相同。

请求

英国的覆盖范围,以及真实响应:

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_with 为 own),并存有产品数据(products_tier 为 own)。first_period 和 latest_period 是来自该机构的已存月份。

参数

参数位置类型必填默认值允许的取值及含义
country查询参数字符串否每个国家一个 ISO 3166-1 alpha-3 代码,大写,或表示欧元区的 EMU。省略时,响应为每个国家一行。不是国家的代码返回 400,没有对应行的国家返回 404。

响应

响应只有一个字段 countries,是一个列表。每一项包含以下字段。

字段含义
country国家,或表示欧元区的 EMU。
partners_tier谁根据 Narwhal 直接存有的数据为伙伴国路由提供数据:own,即该国自己的海关或统计机构;或 partner_reported,即 Narwhal 没有该国本国机构的数据时,使用流向互换后的其他国家的报告。
partner_coverage列出所有伙伴国时为 all,发布机构只列出其主要伙伴国和一个“其余”行时为 top_n。partners_tier 为 partner_reported 时为 null。
products_tier谁为产品路由提供数据:own,或该国没有自己的产品文件时的 partner_reported。UN Comtrade 只有伙伴国总额,因此从不按产品提供数据。
answers_with目前伙伴国路由和产品路由所用的来源,按以下顺序:该国的本国机构(own)、其向 UN Comtrade 的申报(third_party)、其他国家的报告(partner_reported,绝不是官方数据)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按章划分时 UN Comtrade 没有数据,所以由 partner_reported 提供数据。Narwhal 没有该国任何数据时为 null。
tiers_held目前有数据行的每个来源:可为该国提供数据的 basis 值。
first_periodNarwhal 从该国本国机构存有的第一个月份。没有时为 null。
latest_periodNarwhal 从该国本国机构存有的最新月份。没有时为 null。
comtrade_latest_period该国向 UN Comtrade 申报过的最新月份。没有时为 null。
third_party_latest_periodNarwhal 从 UN Comtrade 存有的该国的最新月份。没有时为 null。
comtrade_periods该国向 UN Comtrade 申报过的月份数。
comtrade_latest_year该国向 UN Comtrade 申报过的最新年份。
has_headline该国发布货物贸易月度总额时为 true。
has_services该国发布服务贸易数据时为 true。
has_tariff_book有全国关税税则可用时为 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_tier 为 own,products_tier 为 partner_reported:加拿大的伙伴国数据来自加拿大统计局,其按章划分的产品数据来自其他国家的报告。

未覆盖的国家

一个真实的国家代码但没有数据,返回 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_id。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。

状态代码触发时机
400invalid_querycountry 不是国家代码。
404country_not_coveredNarwhal 在任何来源中都没有该国的贸易数据行。

API 错误码与额度 · 贸易数据 API 参考 · 贸易国家

此页面对你有帮助吗?