开放式贸易查询 API 参考
一次调用查询任意报告国、伙伴国和 HS 章,例如某产品的最大出口国,或一国与另一国的对比。
概览
GET /
GET / 一次调用返回你指定的任意报告国、伙伴国和 HS 章的进出口。reporter、partner 和 hs 各接受最多 10 项的逗号分隔列表。一行对应一个报告国、月份、流向、伙伴国和章。
用它回答跨国家或跨产品的问题:谁出口某一章的产品,一个国家与另一个国家如何贸易,或两个国家并排对比。reporter、partner 和 hs 至少要指定一个。省略 reporter 时,它指 Narwhal 直接存有数据的每个国家,来自其本国机构或 UN Comtrade。
每一行都在 basis、source 和 currency 中注明各自的值,因为各报告国可能由不同的来源提供数据。来自不同来源的行绝不相加。窗口最多 12 个月;不带 start 和 end 时,每个报告国返回其最新月份。不带 hs 时各行是伙伴国总额,带 hs 时是章的行。MCP 工具是 trade_,参数相同。
请求
2026 年 6 月英国和德国 85 章(电机、电气设备)的出口,第一页(五行):
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"DEU"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 396,
"rows": [
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "ABW",
"partner_label": "Aruba",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "108666",
"net_weight_kg": "731"
},
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "AFG",
"partner_label": "Afghanistan",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "153236",
"net_weight_kg": "2893"
}
],
"next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}页面显示五行中的前两行。total 为 396,因此后面还有更多页。第 1 页只有德国的行,reporters 列出该页上的报告国,所以即使请求了两个国家,它也只显示 DEU。
参数
| 参数 | 位置 | 类型 | 必填 | 默认值 | 允许的取值及含义 |
|---|---|---|---|---|---|
reporter | 查询参数 | 字符串 | 否 | Narwhal 直接存有的每个国家 | 报告国,ISO 3166-1 alpha-3 代码,大写,以逗号分隔的列表,最多 10 项,例如 GBR,DEU。不是国家的代码返回 400 并指出该代码。覆盖范围清单之外的国家返回 404 country_。没有任何自有来源的报告国由其他国家的报告提供数据,且需要明确指定。 |
partner | 查询参数 | 字符串 | 否 | 全部伙伴国 | 伙伴国,ISO 3166-1 alpha-3 代码,大写,以逗号分隔的列表,最多 10 项。 |
hs | 查询参数 | 字符串 | 否 | 无 | HS 章,2 位,以逗号分隔的列表,最多 10 项,例如 85,87。此时各行是章的行。省略时,各行是伙伴国总额。开放式查询只存有章的数据。 |
flow | 查询参数 | 字符串 | 否 | 两个流向 | export 或 import。 |
start | 查询参数 | 字符串,YYYY-MM | 否 | 每个报告国的最新月份 | 起始月份,含当月。从 start 到 end 最多 12 个月。 |
end | 查询参数 | 字符串,YYYY-MM | 否 | 每个报告国的最新月份 | 结束月份,含当月。start 和 end 只发送其中一个时,只取该月份。 |
basis | 查询参数 | 字符串 | 否 | 每个报告国已存的最佳来源 | own、third_ 或 partner_。只有该来源提供数据。某个来源对该问题没有数据行时返回 404 basis_。 |
currency | 查询参数 | 字符串 | 否 | 每个报告国自己的货币,在每一行中注明 | USD。用每一行所在月份的每日平均汇率换算。 |
include_ | 查询参数 | 布尔值 | 否 | false | true 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。 |
limit | 查询参数 | 整数 | 否 | 500 | 1 至 1000。一页最多返回的数据行数。 |
cursor | 查询参数 | 字符串 | 否 | 无 | 上一页的 next_,其他所有参数保持不变。 |
响应
响应包含以下字段。
| 字段 | 含义 |
|---|---|
scope | goods。 |
bases | 此响应各行所来自的来源,每个为 own、third_ 或 partner_。 |
reporters | 此页上有数据行的报告国,已排序。后面的页可能列出更多。 |
latest_ | 直接存有的各行中的最新月份。没有时为 null。 |
note | 使用数据前请先阅读。当某一行来自伙伴国报告时设置,其他情况为 null。 |
fx | 带 currency=USD 时:每个月所用的汇率,含 period、from_、to_、rate 和 days。其他情况为 null。 |
calculated | Narwhal 计算的字段名称。 |
total | 所有页中匹配的行数。 |
next_ | 下一页的游标。最后一页为 null。 |
rows 的每一项是一个报告国、月份、流向、伙伴国和章。
| 字段 | 含义 |
|---|---|
reporter | 报告国的 ISO 3166-1 alpha-3 代码。 |
basis | 此行的来源:own、third_ 或 partner_。 |
source | 此行的发布机构。 |
currency | 此行数值的 ISO 4217 代码。 |
flow | export 或 import。 |
period | 月份,YYYY-MM。 |
period_ | month。 |
period_ | 该行所涵盖的第一天和最后一天,YYYY-MM-DD。 |
partner, partner_ | 同伙伴国路由。 |
product_ | 发送了 hs 时的章。伙伴国总额为 null。 |
value | currency 货币的整数单位,为十进制字符串。 |
net_ | 净重,以千克计,发布机构提供时才有。否则为 null。 |
更多示例
只有伙伴国总额的报告国会被跳过
美国自中国的进口,85 章,同时也指定了加拿大和墨西哥。它们的本国机构只提供伙伴国总额,所以只有美国返回数据:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"USA"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 1,
"rows": [
{
"reporter": "USA",
"basis": "own",
"source": "US Census Bureau",
"currency": "USD",
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "5834371932",
"net_weight_kg": null
}
],
"next_cursor": null
}只有伙伴国总额的报告国
当指定的每个报告国都只提供伙伴国总额且发送了 hs 时,调用返回 404,且免费:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"{
"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. See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}来源
每个报告国都由其存有数据的最佳来源提供数据:先是其本国机构,然后是其向 UN Comtrade 的申报(仅伙伴国总额),两者都没有的报告国则由其他国家的报告提供数据,标记为 partner_。按章划分时 UN Comtrade 没有数据。basis 对每个报告国强制使用同一个来源。本国机构只提供伙伴国总额的报告国没有章的行:其他报告国有数据时它被跳过,没有任何报告国能提供数据时,调用返回 404 basis_。
币种
每一行使用其报告国自己的货币,在该行的 currency 中注明。currency=USD 用各行所在月份的每日平均汇率换算,并在 fx 中列出汇率。没有汇率的月份返回 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 | 没有指定 reporter、partner 或 hs(an open query with none is the whole store),end 早于 start,窗口超过 12 个月,某个列表超过 10 项,某个报告国不是国家,某个参数超出允许取值,或发送了 as_ 或 version。当伙伴国报告的响应需要超过 30 个报告国、伙伴国和章的组合时也会如此。 |
400 | invalid_cursor | 游标不是此请求返回的,或者此后另一个参数已改变。 |
400 | range_too_large | 响应会超过 200,000 行,或者没有伙伴国的章的行涵盖超过 36 个报告国月份。请指定更少的报告国、伙伴国或章,或更短的窗口。 |
404 | country_not_covered | 指定的报告国不在覆盖范围清单中(ATA is not in the trade coverage list.)。 |
404 | basis_not_available | basis 指定的来源对该问题没有数据行,或者指定的每个报告国都只有伙伴国总额,同时发送了 hs。 |
404 | rate_not_available | 请求了 currency=USD,但某个月份没有汇率。 |
503 | upstream_unavailable | 汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。 |
503 | trade_data_unavailable | 目前无法读取产品文件。请稍后重试。 |
此页面对你有帮助吗?