浏览全部文档

开放式贸易查询 API 参考

一次调用查询任意报告国、伙伴国和 HS 章,例如某产品的最大出口国,或一国与另一国的对比。

概览

GET /v1/trade/flows

GET /v1/trade/flows 一次调用返回你指定的任意报告国、伙伴国和 HS 章的进出口。reporter、partner 和 hs 各接受最多 10 项的逗号分隔列表。一行对应一个报告国、月份、流向、伙伴国和章。

用它回答跨国家或跨产品的问题:谁出口某一章的产品,一个国家与另一个国家如何贸易,或两个国家并排对比。reporter、partner 和 hs 至少要指定一个。省略 reporter 时,它指 Narwhal 直接存有数据的每个国家,来自其本国机构或 UN Comtrade。

每一行都在 basis、source 和 currency 中注明各自的值,因为各报告国可能由不同的来源提供数据。来自不同来源的行绝不相加。窗口最多 12 个月;不带 start 和 end 时,每个报告国返回其最新月份。不带 hs 时各行是伙伴国总额,带 hs 时是章的行。MCP 工具是 trade_get_flows,参数相同。

请求

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"
85 章出口,英国和德国
{
  "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_not_covered。没有任何自有来源的报告国由其他国家的报告提供数据,且需要明确指定。
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_party 或 partner_reported。只有该来源提供数据。某个来源对该问题没有数据行时返回 404 basis_not_available。
currency查询参数字符串否每个报告国自己的货币,在每一行中注明USD。用每一行所在月份的每日平均汇率换算。
include_groups查询参数布尔值否falsetrue 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。
limit查询参数整数否5001 至 1000。一页最多返回的数据行数。
cursor查询参数字符串否无上一页的 next_cursor,其他所有参数保持不变。

响应

响应包含以下字段。

字段含义
scopegoods。
bases此响应各行所来自的来源,每个为 own、third_party 或 partner_reported。
reporters此页上有数据行的报告国,已排序。后面的页可能列出更多。
latest_period直接存有的各行中的最新月份。没有时为 null。
note使用数据前请先阅读。当某一行来自伙伴国报告时设置,其他情况为 null。
fx带 currency=USD 时:每个月所用的汇率,含 period、from_currency、to_currency、rate 和 days。其他情况为 null。
calculatedNarwhal 计算的字段名称。
total所有页中匹配的行数。
next_cursor下一页的游标。最后一页为 null。

rows 的每一项是一个报告国、月份、流向、伙伴国和章。

字段含义
reporter报告国的 ISO 3166-1 alpha-3 代码。
basis此行的来源:own、third_party 或 partner_reported。
source此行的发布机构。
currency此行数值的 ISO 4217 代码。
flowexport 或 import。
period月份,YYYY-MM。
period_typemonth。
period_start, period_end该行所涵盖的第一天和最后一天,YYYY-MM-DD。
partner, partner_label, partner_kind, unallocated_reason同伙伴国路由。
product_code发送了 hs 时的章。伙伴国总额为 null。
valuecurrency 货币的整数单位,为十进制字符串。
net_weight_kg净重,以千克计,发布机构提供时才有。否则为 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"
自中国的 85 章进口
{
  "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"
加拿大,85 章
{
  "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_reported。按章划分时 UN Comtrade 没有数据。basis 对每个报告国强制使用同一个来源。本国机构只提供伙伴国总额的报告国没有章的行:其他报告国有数据时它被跳过,没有任何报告国能提供数据时,调用返回 404 basis_not_available。

币种

每一行使用其报告国自己的货币,在该行的 currency 中注明。currency=USD 用各行所在月份的每日平均汇率换算,并在 fx 中列出汇率。没有汇率的月份返回 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没有指定 reporter、partner 或 hs(an open query with none is the whole store),end 早于 start,窗口超过 12 个月,某个列表超过 10 项,某个报告国不是国家,某个参数超出允许取值,或发送了 as_of 或 version。当伙伴国报告的响应需要超过 30 个报告国、伙伴国和章的组合时也会如此。
400invalid_cursor游标不是此请求返回的,或者此后另一个参数已改变。
400range_too_large响应会超过 200,000 行,或者没有伙伴国的章的行涵盖超过 36 个报告国月份。请指定更少的报告国、伙伴国或章,或更短的窗口。
404country_not_covered指定的报告国不在覆盖范围清单中(ATA is not in the trade coverage list.)。
404basis_not_availablebasis 指定的来源对该问题没有数据行,或者指定的每个报告国都只有伙伴国总额,同时发送了 hs。
404rate_not_available请求了 currency=USD,但某个月份没有汇率。
503upstream_unavailable汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。
503trade_data_unavailable目前无法读取产品文件。请稍后重试。

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

此页面对你有帮助吗?