贸易数据 API 参考
按伙伴国和 HS 产品逐月读取货物贸易数据:Narwhal 存有该国数据的,取自该国的海关或统计机构;其余国家取自 UN Comtrade 或其他国家的报告。
概览
贸易数据 API 按伙伴国和产品返回货物贸易数据,每次一个月。一行是一个月内的一个流向(出口或进口),对应一个伙伴国或一个产品,并带有以某种货币的整数单位表示的数值。产品遵循协调制度(HS),分 2 位、4 位和 6 位。来源有发布的,历史数据自 2010 年 1 月起。该 API 只涵盖货物。
数据来自报告国的海关或统计机构(Narwhal 存有其数据的国家),覆盖范围清单中 181 个国家里的其余国家,则取自 UN Comtrade 或其他国家的报告。每个响应都注明由哪个来源提供。各国由哪个来源提供数据,见贸易国家页面。
共有七个路由,均位于 / 之下,每个路由同时也是一个 MCP 工具,参数和响应都相同。每个请求都在 Authorization: Bearer 请求头中携带密钥,与 Narwhal 的其他部分一致。
路由
| 路由 | MCP 工具 | 返回内容 |
|---|---|---|
GET / | trade_ | 某一国家按伙伴国划分的进出口。 |
GET / | trade_ | 某一国家按 HS 产品划分的进出口,分 2、4 或 6 位。 |
GET / | trade_ | 某一国家某个 HS 编码与每个伙伴国的贸易。 |
GET / | trade_ | 对多个报告国、伙伴国和章的开放式查询。 |
GET / | trade_ | 各国由哪个来源提供数据,以及已存的月份。免费。 |
GET / | trade_ | 按名称、级别或上级搜索或列出 HS 编码。 |
GET / | trade_ | 一个 HS 编码及其上级和下级编码。 |
每个路由都有自己的页面,列出每个参数、一个可运行的请求及其真实响应,以及每个错误。
来源
每个响应来自一个来源,在 basis 和 source 中注明。不带 basis 的请求,取下列顺序中第一个存有数据行的来源。同一响应绝不混用多个来源,basis 用于按名称指定一个来源。
basis | 来源 | 说明 | 达到 |
|---|---|---|---|
own | 该国自己的海关或统计机构 | 该机构自己的数据,以其自身的货币,按发布原样提供。 | 伙伴国;机构提供产品数据时,另有 2 位、4 位和 6 位的产品 |
third_ | UN Comtrade | 该国向联合国提交的自己的月度申报数据,并注明来源。 | 仅伙伴国总额 |
partner_ | 其他国家的海关报告 | 其他国家对该国的报告,进出口流向互换:它们从该国的进口即为该国的出口。这是另一种计量,绝不是官方数据。 | 伙伴国,以及 2 位的产品 |
只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时 UN Comtrade 没有数据,所以顺序是 own,然后是 partner_。伙伴国报告的响应没有官方总额,不接受 top、share、ytd 或 change,最多涵盖 12 个月。GET / 显示 answers_,即目前为各国提供数据的来源。
各国由哪个来源提供数据: 贸易国家。
币种
数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币。currency=USD 用当月每日汇率的平均值换算每个月,在 fx 中列出每个月所用的汇率,并在 calculated 中列出被换算的字段。开放式查询路由在每一行中注明货币,因为各报告国以不同货币发布。
分页
limit 设定一页最多返回的数据行数,范围 1 至 1000。伙伴国、产品、单个产品和开放式查询路由默认为 500,GET / 默认为 100。匹配的行多于一页时,next_ 含下一页的游标:将其作为 cursor 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。
价格
贸易调用每 1,000 次调用 $2。返回至少一行数据的请求算一次调用,长响应的每一页也算一次调用。没有数据行的响应免费,每个错误都免费,覆盖范围路由也免费。额度和充值见价格。
错误
错误采用通用的错误响应格式,并带有 request_。每个路由页面列出该路由可能返回的错误。以下是全部错误。
| 状态 | 代码 | 触发时机 |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | 缺少或无效的密钥、余额低于一次调用的价格,或每分钟请求过多。见 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 | hs_code_not_found | HS 版本没有该编码。 |
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 | 目前无法读取产品文件。请稍后重试。 |
MCP 工具
每个路由都是一个独立的 MCP 工具,参数和响应相同。MCP 工具一次结果最多返回 200 行,因此请用 cursor 翻页。这些工具是:
trade_ list_ hs_ codestrade_ get_ hs_ codetrade_ get_ coveragetrade_ get_ partnerstrade_ get_ productstrade_ get_ producttrade_ get_ flows此页面对你有帮助吗?