浏览全部文档

按伙伴国划分的贸易 API 参考

读取一个国家按伙伴国划分的进出口,每个伙伴国、每个月、每个流向一行,并在各行之和旁附上发布机构自己的总额。

概览

GET /v1/trade/{country}/partners

GET /v1/trade/{country}/partners 返回一个国家按伙伴国划分的货物贸易:每个伙伴国、每个月、每个流向一行。不带 start 和 end 时,响应是已存的最新月份。

用它了解一个国家与谁贸易以及贸易额多少。同一国家按产品划分请用产品路由,一个产品对应每个伙伴国请用单个产品路由。一次调用比较多个国家请用开放式查询路由。

每个响应都在 basis 和 source 中注明产生数据的来源,并在 totals 中,于各行之和旁附上发布机构自己的总额。带 hs 时,totals 是该产品的总额,official_total 为 null。MCP 工具是 trade_get_partners,参数相同。

请求

2026 年 6 月英国的三大出口伙伴国,以及真实响应:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"
英国,三大出口伙伴国
{
  "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": "37649508686",
      "sum_of_rows": "37649508686"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows",
    "rank"
  ],
  "total": 3,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "5316654916",
      "net_weight_kg": "76287894",
      "rank": 1,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "4735227787",
      "net_weight_kg": "341314142",
      "rank": 2,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

页面显示三行中的前两行。basis 为 own,所以由英国税务海关总署(HM Revenue & Customs)提供数据,且 official_total 等于 sum_of_rows。因为发送了 top,所以设置了 rank,calculated 中列出了它。

参数

参数位置类型必填默认值允许的取值及含义
country路径参数字符串是无报告国的 ISO 3166-1 alpha-3 代码,大写,例如 GBR。不是国家的代码返回 400。没有数据的国家返回 404 country_not_covered。
partner查询参数字符串否全部伙伴国一个伙伴国的 ISO 3166-1 alpha-3 代码,大写。不是该国伙伴国的代码返回 400 unknown_partner。
flow查询参数字符串否两个流向export 或 import。
start查询参数字符串,YYYY-MM否已存的最新月份起始月份,含当月。有 start 而没有 end 时,响应截至已存的最新月份。start 晚于 end 返回 400。
end查询参数字符串,YYYY-MM否已存的最新月份结束月份,含当月。只有 end 时,响应是不晚于它的已存最新月份。
hs查询参数字符串否全部产品只取该产品的贸易,编码为 2、4 或 6 位(85、8517、851713):显示每个伙伴国在其中的占比。其他位数的编码返回 400。泰国按 4 位保存,因此对泰国使用 6 位编码返回 404 basis_not_available。
basis查询参数字符串否已存的最佳来源own、third_party 或 partner_reported。按名称指定一个来源,并跳过顺序。某个来源对该问题没有数据时返回 404 basis_not_available。
currency查询参数字符串否来源自己的货币USD。用每个月的每日平均汇率换算。
top查询参数整数否全部数据行1 至 1000。保留每个月、每个流向中最大的 N 个国家行,按数值排序,数值相同时按伙伴国代码决定先后,并给每行加上 rank。组行和未分配行不排名。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
share查询参数布尔值否falsetrue 为每行加上 share:其数值除以同一月份、同一流向的国家行之和,以 1 的小数表示,保留 6 位小数。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
ytd查询参数布尔值否falsetrue 把一月至 end(默认:最新月份)已存的各月份求和,period_type 为 year_to_date。请发送 end 而不是 start:带 start 的请求返回 400。缺少某个月份返回 404 period_not_published。计算所得。不适用于伙伴国报告的响应。
change查询参数布尔值否falsetrue 为每行加上 change:一年前的同一个月(或年初至今),以及差额和双方的发布状态。缺少一年前的月份返回 404 period_not_published。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
include_groups查询参数布尔值否falsetrue 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。
limit查询参数整数否5001 至 1000。一页最多返回的数据行数。
cursor查询参数字符串否无上一页的 next_cursor,其他所有参数保持不变。

响应

响应包含以下字段。对每一行都相同的内容在这里只出现一次。

字段含义
country响应所针对的报告国的 ISO 3166-1 alpha-3 代码。
basis提供数据的来源:own、third_party(UN Comtrade)或 partner_reported。
source发布机构,例如 HM Revenue & Customs、Eurostat Comext、UN Comtrade 或 Customs reports of other countries。
reporters_included对于 partner_reported:其报告被互换后纳入响应的报告国的 count 和 countries。其他来源为 null。
note使用数据前请先阅读。伙伴国报告的响应会设置此项,其他情况为 null。
coveragefull 或 partial。伙伴国报告的响应为 partial。
partner_coverage列出所有伙伴国时为 all,发布机构只列出其主要伙伴国和一个“其余”行时为 top_n。伙伴国报告的响应为 null。
scopegoods。
currency响应中所有数值的 ISO 4217 代码。
classificationHS,即协调制度。
edition一个版本涵盖所查询的每个月份时的 HS 版本(2007、2012、2017 或 2022)。各月份不同时为 null,此时每一行注明各自的版本。
edition_basis发布机构说明版本时为 as_published,Narwhal 根据年份推断时为 inferred_from_year。
valuation_basis发布机构如何对贸易估价,例如出口按离岸价(FOB)、进口按到岸价(CIF)。未说明时为 not_stated。
trade_system发布机构有说明时为 general 或 special。否则为 not_stated。
partner_basis伙伴国按原产地、起运地还是目的地统计,以发布机构的说明为准。否则为 not_stated。
trade_scope数据所涵盖的内容,例如 all_partners、extra_union_only 或 intra_union_other_method。
latest_periodNarwhal 存有的该国该来源的最新月份。
total_basisofficial_total 的口径:customs、balance_of_payments 或 eurostat_concept。发布机构不提供总额时为 null。
totals每个月、每个流向一项:period、flow、official_total(发布机构自己的货物总额,没有时为 null)和 sum_of_rows(该月该流向除组行外所有伙伴国行之和,计算所得)。不带 hs 时,它是该月的全部货物总额,即使 partner 限定了行也是如此。带 hs 时(以及在单个产品路由上),它改为该产品的总额:sum_of_rows 是响应所有页中各行之和(若指定了 partner,则为该伙伴国的行;top 和分页不会削减它),official_total 为 null,因为发布机构不为单个产品列出总额。
fx带 currency=USD 时,以及伙伴国报告的响应含多种货币时:每个月所用的汇率,含 period、from_currency、to_currency、rate 和平均所含的 days。其他情况为 null。
calculatedNarwhal 计算的字段名称,例如 sum_of_rows、rank、share、value 或 official_total。
total所有页中匹配的行数。
next_cursor下一页的游标。最后一页为 null。

rows 的每一项是一个伙伴国在一个月、一个流向上的数据。

字段含义
flowexport 或 import。
period月份,YYYY-MM。对于年初至今,为其最后一个月。
period_typemonth 或 year_to_date。
period_start, period_end该行所涵盖的第一天和最后一天,YYYY-MM-DD。
valuecurrency 货币的整数单位,为十进制字符串。
net_weight_kg净重,以千克计,为十进制字符串,发布机构提供时才有。否则为 null。
rank带 top 时:该行的排名,最大者为 1。否则为 null。
share带 share 时:该行占总额的比例,保留 6 位小数。否则为 null。
change带 change 时:一个对象,含 previous_period、previous_value、absolute(数值减去上期数值)、percent(以百分数表示,保留 4 位小数,前值为 0 时为 null)、release_status 和 previous_release_status(preliminary、revised、final,发布机构未说明时为 null)。一年前的行不存在或未请求 change 时为 null。
partner伙伴国的 ISO 3166-1 alpha-3 代码、EUU 这样的组代码,或没有国家的行为空。
partner_label发布机构自己使用的伙伴国名称。
partner_kindcountry、group 或 unallocated。
unallocated_reason对于未分配行:not_specified、confidential、stores_bunkers、free_zone、other 或 rest。否则为 null。

更多示例

一个伙伴国的两个流向

德国与中国,2026 年 1 月至 6 月,两个流向:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"
德国与中国
{
  "country": "DEU",
  "basis": "own",
  "source": "Eurostat Comext",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "EUR",
  "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": "eurostat_concept",
  "totals": [
    {
      "period": "2026-01",
      "flow": "export",
      "official_total": "121792305000",
      "sum_of_rows": "121792305000"
    },
    {
      "period": "2026-01",
      "flow": "import",
      "official_total": "106754947046",
      "sum_of_rows": "106754947046"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 12,
  "rows": [
    {
      "flow": "export",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "5559611667",
      "net_weight_kg": "355538457",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "8853410701",
      "net_weight_kg": "1020758294",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

页面显示 12 行中的前两行,以及 12 个 totals 项中的前两项。德国的数据来自 Eurostat Comext,以欧元计。

该国自己的机构不提供的产品

加拿大的机构只提供伙伴国总额。请求单个产品返回 404,且免费:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"
加拿大,产品 8517
{
  "type": "https://narwhalapi.com/problems/basis-not-available",
  "title": "Basis not available",
  "status": 404,
  "detail": "Narwhal holds CAN's own partner totals only, not its products; UN Comtrade is held as partner totals only, not by product; partner-reported answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}

来源

每个请求由一个来源提供数据,即按以下顺序第一个存有数据行的来源:该国自己的海关或统计机构(basis 为 own)、该国向 UN Comtrade 的申报(third_party,仅伙伴国总额),然后是其他国家对该国的报告,进出口流向互换(partner_reported)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时,UN Comtrade 没有数据,所以顺序是 own,然后是 partner_reported,且 partner_reported 只到章(2 位)。basis 用于按名称指定一个来源。响应中的 basis、source 和 note 字段说明由哪个来源提供数据,同一响应绝不混用多个来源。伙伴国报告的响应与该国自己的数据是不同的计量,绝不是官方数据。一个来源的伙伴国列表可能很短:当 partner_coverage 为 top_n 时,发布机构只列出其主要伙伴国和一个“其余”行,各行加总仍等于总额。

币种

数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币,例如英国税务海关总署(HM Revenue & Customs)为 GBP。currency=USD 用当月每日汇率的平均值换算每个月。每个月所用的汇率列在 fx 中,calculated 列出被换算的字段。没有汇率的月份返回 404 rate_not_available。如果汇率来源无法响应,请求返回 503 upstream_unavailable。已经是美元的响应保持原样返回。

分页

limit 设定一页最多返回的数据行数,范围 1 至 1000,默认 500。匹配的行多于一页时,next_cursor 含下一页的游标:将其作为 cursor 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_cursor。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。

价格

返回至少一行数据的请求算一次调用,每 1,000 次调用 $2。长响应的每一页都算一次调用,与 limit 无关。没有数据行的响应免费,每个错误也免费。

错误

这些错误采用通用的错误响应格式,并带有 request_id。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。

状态代码触发时机
400invalid_query参数缺失、格式错误或超出允许取值,例如 start=2026-13、start 晚于 end、ytd 与 start 一起发送,或发送了 as_of 或 version(这些路由提供当前已存的数据)。对伙伴国报告的响应请求 top、share、ytd 或 change 时也会如此。
400invalid_cursor游标不是此请求返回的,或者此后另一个参数已改变。
400unknown_partnerpartner 在所查询的月份中不是该国的伙伴国,例如 ZZZ is not a partner of GBR.
400range_too_largetop、share、ytd 或 change 涵盖超过 12 个月,伙伴国报告的响应涵盖超过 12 个月,或任一级别(2、4 或 6 位)的产品响应在没有 hs 或 partner 的情况下涵盖已存的超过 12 个月。开放式查询对超过 12 个月的窗口返回 invalid_query。
404country_not_coveredNarwhal 在任何来源中都没有该国的贸易数据行。
404period_not_published所查询的月份未存入(No trade rows for 2026-10.),或 ytd 或 change 所需的某个月份缺失。
404basis_not_available所指定的来源,或顺序中的每个来源,对该问题都没有数据。detail 说明原因,例如该国自己的机构只提供伙伴国总额而不提供产品,或伙伴国报告的响应只到章(2 位),或泰国自己的机构只保存 4 位而请求了 6 位。见覆盖范围路由。
404rate_not_available请求了 currency=USD,但某个月份没有汇率。
503upstream_unavailable汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。
503trade_data_unavailable目前无法读取产品文件。请稍后重试。

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

此页面对你有帮助吗?