按伙伴国划分的贸易 API 参考
读取一个国家按伙伴国划分的进出口,每个伙伴国、每个月、每个流向一行,并在各行之和旁附上发布机构自己的总额。
概览
GET /
GET / 返回一个国家按伙伴国划分的货物贸易:每个伙伴国、每个月、每个流向一行。不带 start 和 end 时,响应是已存的最新月份。
用它了解一个国家与谁贸易以及贸易额多少。同一国家按产品划分请用产品路由,一个产品对应每个伙伴国请用单个产品路由。一次调用比较多个国家请用开放式查询路由。
每个响应都在 basis 和 source 中注明产生数据的来源,并在 totals 中,于各行之和旁附上发布机构自己的总额。带 hs 时,totals 是该产品的总额,official_ 为 null。MCP 工具是 trade_,参数相同。
请求
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_ 等于 sum_。因为发送了 top,所以设置了 rank,calculated 中列出了它。
参数
| 参数 | 位置 | 类型 | 必填 | 默认值 | 允许的取值及含义 |
|---|---|---|---|---|---|
country | 路径参数 | 字符串 | 是 | 无 | 报告国的 ISO 3166-1 alpha-3 代码,大写,例如 GBR。不是国家的代码返回 400。没有数据的国家返回 404 country_。 |
partner | 查询参数 | 字符串 | 否 | 全部伙伴国 | 一个伙伴国的 ISO 3166-1 alpha-3 代码,大写。不是该国伙伴国的代码返回 400 unknown_。 |
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_。 |
basis | 查询参数 | 字符串 | 否 | 已存的最佳来源 | own、third_ 或 partner_。按名称指定一个来源,并跳过顺序。某个来源对该问题没有数据时返回 404 basis_。 |
currency | 查询参数 | 字符串 | 否 | 来源自己的货币 | USD。用每个月的每日平均汇率换算。 |
top | 查询参数 | 整数 | 否 | 全部数据行 | 1 至 1000。保留每个月、每个流向中最大的 N 个国家行,按数值排序,数值相同时按伙伴国代码决定先后,并给每行加上 rank。组行和未分配行不排名。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
share | 查询参数 | 布尔值 | 否 | false | true 为每行加上 share:其数值除以同一月份、同一流向的国家行之和,以 1 的小数表示,保留 6 位小数。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
ytd | 查询参数 | 布尔值 | 否 | false | true 把一月至 end(默认:最新月份)已存的各月份求和,period_ 为 year_。请发送 end 而不是 start:带 start 的请求返回 400。缺少某个月份返回 404 period_。计算所得。不适用于伙伴国报告的响应。 |
change | 查询参数 | 布尔值 | 否 | false | true 为每行加上 change:一年前的同一个月(或年初至今),以及差额和双方的发布状态。缺少一年前的月份返回 404 period_。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
include_ | 查询参数 | 布尔值 | 否 | false | true 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。 |
limit | 查询参数 | 整数 | 否 | 500 | 1 至 1000。一页最多返回的数据行数。 |
cursor | 查询参数 | 字符串 | 否 | 无 | 上一页的 next_,其他所有参数保持不变。 |
响应
响应包含以下字段。对每一行都相同的内容在这里只出现一次。
| 字段 | 含义 |
|---|---|
country | 响应所针对的报告国的 ISO 3166-1 alpha-3 代码。 |
basis | 提供数据的来源:own、third_(UN Comtrade)或 partner_。 |
source | 发布机构,例如 HM Revenue & Customs、Eurostat Comext、UN Comtrade 或 Customs reports of other countries。 |
reporters_ | 对于 partner_:其报告被互换后纳入响应的报告国的 count 和 countries。其他来源为 null。 |
note | 使用数据前请先阅读。伙伴国报告的响应会设置此项,其他情况为 null。 |
coverage | full 或 partial。伙伴国报告的响应为 partial。 |
partner_ | 列出所有伙伴国时为 all,发布机构只列出其主要伙伴国和一个“其余”行时为 top_。伙伴国报告的响应为 null。 |
scope | goods。 |
currency | 响应中所有数值的 ISO 4217 代码。 |
classification | HS,即协调制度。 |
edition | 一个版本涵盖所查询的每个月份时的 HS 版本(2007、2012、2017 或 2022)。各月份不同时为 null,此时每一行注明各自的版本。 |
edition_ | 发布机构说明版本时为 as_,Narwhal 根据年份推断时为 inferred_。 |
valuation_ | 发布机构如何对贸易估价,例如出口按离岸价(FOB)、进口按到岸价(CIF)。未说明时为 not_。 |
trade_ | 发布机构有说明时为 general 或 special。否则为 not_。 |
partner_ | 伙伴国按原产地、起运地还是目的地统计,以发布机构的说明为准。否则为 not_。 |
trade_ | 数据所涵盖的内容,例如 all_、extra_ 或 intra_。 |
latest_ | Narwhal 存有的该国该来源的最新月份。 |
total_ | official_ 的口径:customs、balance_ 或 eurostat_。发布机构不提供总额时为 null。 |
totals | 每个月、每个流向一项:period、flow、official_(发布机构自己的货物总额,没有时为 null)和 sum_(该月该流向除组行外所有伙伴国行之和,计算所得)。不带 hs 时,它是该月的全部货物总额,即使 partner 限定了行也是如此。带 hs 时(以及在单个产品路由上),它改为该产品的总额:sum_ 是响应所有页中各行之和(若指定了 partner,则为该伙伴国的行;top 和分页不会削减它),official_ 为 null,因为发布机构不为单个产品列出总额。 |
fx | 带 currency=USD 时,以及伙伴国报告的响应含多种货币时:每个月所用的汇率,含 period、from_、to_、rate 和平均所含的 days。其他情况为 null。 |
calculated | Narwhal 计算的字段名称,例如 sum_、rank、share、value 或 official_。 |
total | 所有页中匹配的行数。 |
next_ | 下一页的游标。最后一页为 null。 |
rows 的每一项是一个伙伴国在一个月、一个流向上的数据。
| 字段 | 含义 |
|---|---|
flow | export 或 import。 |
period | 月份,YYYY-MM。对于年初至今,为其最后一个月。 |
period_ | month 或 year_。 |
period_ | 该行所涵盖的第一天和最后一天,YYYY-MM-DD。 |
value | currency 货币的整数单位,为十进制字符串。 |
net_ | 净重,以千克计,为十进制字符串,发布机构提供时才有。否则为 null。 |
rank | 带 top 时:该行的排名,最大者为 1。否则为 null。 |
share | 带 share 时:该行占总额的比例,保留 6 位小数。否则为 null。 |
change | 带 change 时:一个对象,含 previous_、previous_、absolute(数值减去上期数值)、percent(以百分数表示,保留 4 位小数,前值为 0 时为 null)、release_ 和 previous_(preliminary、revised、final,发布机构未说明时为 null)。一年前的行不存在或未请求 change 时为 null。 |
partner | 伙伴国的 ISO 3166-1 alpha-3 代码、EUU 这样的组代码,或没有国家的行为空。 |
partner_ | 发布机构自己使用的伙伴国名称。 |
partner_ | country、group 或 unallocated。 |
unallocated_ | 对于未分配行:not_、confidential、stores_、free_、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"{
"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_,仅伙伴国总额),然后是其他国家对该国的报告,进出口流向互换(partner_)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时,UN Comtrade 没有数据,所以顺序是 own,然后是 partner_,且 partner_ 只到章(2 位)。basis 用于按名称指定一个来源。响应中的 basis、source 和 note 字段说明由哪个来源提供数据,同一响应绝不混用多个来源。伙伴国报告的响应与该国自己的数据是不同的计量,绝不是官方数据。一个来源的伙伴国列表可能很短:当 partner_ 为 top_ 时,发布机构只列出其主要伙伴国和一个“其余”行,各行加总仍等于总额。
币种
数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币,例如英国税务海关总署(HM Revenue & Customs)为 GBP。currency=USD 用当月每日汇率的平均值换算每个月。每个月所用的汇率列在 fx 中,calculated 列出被换算的字段。没有汇率的月份返回 404 rate_。如果汇率来源无法响应,请求返回 503 upstream_。已经是美元的响应保持原样返回。
分页
limit 设定一页最多返回的数据行数,范围 1 至 1000,默认 500。匹配的行多于一页时,next_ 含下一页的游标:将其作为 cursor 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。
价格
返回至少一行数据的请求算一次调用,每 1,000 次调用 $2。长响应的每一页都算一次调用,与 limit 无关。没有数据行的响应免费,每个错误也免费。
错误
这些错误采用通用的错误响应格式,并带有 request_。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。
| 状态 | 代码 | 触发时机 |
|---|---|---|
400 | invalid_query | 参数缺失、格式错误或超出允许取值,例如 start=2026-13、start 晚于 end、ytd 与 start 一起发送,或发送了 as_ 或 version(这些路由提供当前已存的数据)。对伙伴国报告的响应请求 top、share、ytd 或 change 时也会如此。 |
400 | invalid_cursor | 游标不是此请求返回的,或者此后另一个参数已改变。 |
400 | unknown_partner | partner 在所查询的月份中不是该国的伙伴国,例如 ZZZ is not a partner of GBR. |
400 | range_too_large | top、share、ytd 或 change 涵盖超过 12 个月,伙伴国报告的响应涵盖超过 12 个月,或任一级别(2、4 或 6 位)的产品响应在没有 hs 或 partner 的情况下涵盖已存的超过 12 个月。开放式查询对超过 12 个月的窗口返回 invalid_。 |
404 | country_not_covered | Narwhal 在任何来源中都没有该国的贸易数据行。 |
404 | period_not_published | 所查询的月份未存入(No trade rows for 2026-10.),或 ytd 或 change 所需的某个月份缺失。 |
404 | basis_not_available | 所指定的来源,或顺序中的每个来源,对该问题都没有数据。detail 说明原因,例如该国自己的机构只提供伙伴国总额而不提供产品,或伙伴国报告的响应只到章(2 位),或泰国自己的机构只保存 4 位而请求了 6 位。见覆盖范围路由。 |
404 | rate_not_available | 请求了 currency=USD,但某个月份没有汇率。 |
503 | upstream_unavailable | 汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。 |
503 | trade_data_unavailable | 目前无法读取产品文件。请稍后重试。 |
此页面对你有帮助吗?