浏览全部文档

贸易数据 API 参考

按伙伴国和 HS 产品逐月读取货物贸易数据:Narwhal 存有该国数据的,取自该国的海关或统计机构;其余国家取自 UN Comtrade 或其他国家的报告。

概览

贸易数据 API 按伙伴国和产品返回货物贸易数据,每次一个月。一行是一个月内的一个流向(出口或进口),对应一个伙伴国或一个产品,并带有以某种货币的整数单位表示的数值。产品遵循协调制度(HS),分 2 位、4 位和 6 位。来源有发布的,历史数据自 2010 年 1 月起。该 API 只涵盖货物。

数据来自报告国的海关或统计机构(Narwhal 存有其数据的国家),覆盖范围清单中 181 个国家里的其余国家,则取自 UN Comtrade 或其他国家的报告。每个响应都注明由哪个来源提供。各国由哪个来源提供数据,见贸易国家页面。

共有七个路由,均位于 /v1/trade 之下,每个路由同时也是一个 MCP 工具,参数和响应都相同。每个请求都在 Authorization: Bearer 请求头中携带密钥,与 Narwhal 的其他部分一致。

路由

路由MCP 工具返回内容
GET /v1/trade/{country}/partnerstrade_get_partners某一国家按伙伴国划分的进出口。
GET /v1/trade/{country}/productstrade_get_products某一国家按 HS 产品划分的进出口,分 2、4 或 6 位。
GET /v1/trade/{country}/products/{hs}trade_get_product某一国家某个 HS 编码与每个伙伴国的贸易。
GET /v1/trade/flowstrade_get_flows对多个报告国、伙伴国和章的开放式查询。
GET /v1/trade/coveragetrade_get_coverage各国由哪个来源提供数据,以及已存的月份。免费。
GET /v1/trade/hs-codestrade_list_hs_codes按名称、级别或上级搜索或列出 HS 编码。
GET /v1/trade/hs-codes/{code}trade_get_hs_code一个 HS 编码及其上级和下级编码。

每个路由都有自己的页面,列出每个参数、一个可运行的请求及其真实响应,以及每个错误。

来源

每个响应来自一个来源,在 basis 和 source 中注明。不带 basis 的请求,取下列顺序中第一个存有数据行的来源。同一响应绝不混用多个来源,basis 用于按名称指定一个来源。

basis来源说明达到
own该国自己的海关或统计机构该机构自己的数据,以其自身的货币,按发布原样提供。伙伴国;机构提供产品数据时,另有 2 位、4 位和 6 位的产品
third_partyUN Comtrade该国向联合国提交的自己的月度申报数据,并注明来源。仅伙伴国总额
partner_reported其他国家的海关报告其他国家对该国的报告,进出口流向互换:它们从该国的进口即为该国的出口。这是另一种计量,绝不是官方数据。伙伴国,以及 2 位的产品

只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时 UN Comtrade 没有数据,所以顺序是 own,然后是 partner_reported。伙伴国报告的响应没有官方总额,不接受 top、share、ytd 或 change,最多涵盖 12 个月。GET /v1/trade/coverage 显示 answers_with,即目前为各国提供数据的来源。

各国由哪个来源提供数据: 贸易国家。

币种

数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币。currency=USD 用当月每日汇率的平均值换算每个月,在 fx 中列出每个月所用的汇率,并在 calculated 中列出被换算的字段。开放式查询路由在每一行中注明货币,因为各报告国以不同货币发布。

分页

limit 设定一页最多返回的数据行数,范围 1 至 1000。伙伴国、产品、单个产品和开放式查询路由默认为 500,GET /v1/trade/hs-codes 默认为 100。匹配的行多于一页时,next_cursor 含下一页的游标:将其作为 cursor 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_cursor。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。

价格

贸易调用每 1,000 次调用 $2。返回至少一行数据的请求算一次调用,长响应的每一页也算一次调用。没有数据行的响应免费,每个错误都免费,覆盖范围路由也免费。额度和充值见价格。

错误

错误采用通用的错误响应格式,并带有 request_id。每个路由页面列出该路由可能返回的错误。以下是全部错误。

状态代码触发时机
401, 402, 429unauthorized, insufficient_credits, rate_limited缺少或无效的密钥、余额低于一次调用的价格,或每分钟请求过多。见 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。
404hs_code_not_foundHS 版本没有该编码。
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 参考 · 贸易国家

MCP 工具

每个路由都是一个独立的 MCP 工具,参数和响应相同。MCP 工具一次结果最多返回 200 行,因此请用 cursor 翻页。这些工具是:

trade_list_hs_codestrade_get_hs_codetrade_get_coveragetrade_get_partnerstrade_get_productstrade_get_producttrade_get_flows

此页面对你有帮助吗?