浏览全部文档

单个产品贸易 API 参考

读取一个国家一个 HS 编码与每个伙伴国的进出口,每个伙伴国、每个月、每个流向一行,并附上该编码的名称。

概览

GET /v1/trade/{country}/products/{hs}

GET /v1/trade/{country}/products/{hs} 返回一个国家某个 HS 编码与每个伙伴国的贸易:每个伙伴国、每个月、每个流向一行,并附上该编码的名称。hs 是 2、4 或 6 位的编码。

用它了解哪些伙伴国买入或卖出某个产品。它的选项与伙伴国路由相同,带 hs 的伙伴国请求返回相同的数据。

HS 版本中没有的编码返回 404 hs_code_not_found。MCP 工具是 trade_get_product,参数相同。

请求

2026 年 6 月英国对美国的 8517 品目(电话机及其他发送或接收数据的设备)数据,以及真实响应:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/8517?partner=USA&start=2026-06&end=2026-06"
英国,品目 8517,对美国
{
  "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": null,
      "sum_of_rows": "46135455"
    },
    {
      "period": "2026-06",
      "flow": "import",
      "official_total": null,
      "sum_of_rows": "89090099"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 2,
  "product_code": "8517",
  "product_level": 4,
  "product_label": "Telephone sets, incl. telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, incl. apparatus for communication in a wired or wireless network [such as a local or wide area network]; parts thereof (excl. than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528)",
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "46135455",
      "net_weight_kg": "74435",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "89090099",
      "net_weight_kg": "246068",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

每个流向一行。totals 含 8517 品目与美国的总额,即两行之和,official_total 为 null,因为发布机构不为单个产品列出总额。

参数

参数位置类型必填默认值允许的取值及含义
country路径参数字符串是无报告国的 ISO 3166-1 alpha-3 代码,大写,例如 GBR。不是国家的代码返回 400。没有数据的国家返回 404 country_not_covered。
hs路径参数字符串是无2、4 或 6 位的 HS 编码,例如 85、8517 或 851713。其他位数返回 400。在 HS 版本中没有名称且该国没有数据行的编码返回 404 hs_code_not_found。泰国按 4 位保存,因此对泰国使用 6 位编码返回 404 basis_not_available。
partner查询参数字符串否全部伙伴国一个伙伴国的 ISO 3166-1 alpha-3 代码,大写。不是该国伙伴国的代码返回 400 unknown_partner。
flow查询参数字符串否两个流向export 或 import。
start查询参数字符串,YYYY-MM否已存的最新月份起始月份,含当月。有 start 而没有 end 时,响应截至已存的最新月份。start 晚于 end 返回 400。
end查询参数字符串,YYYY-MM否已存的最新月份结束月份,含当月。只有 end 时,响应是不晚于它的已存最新月份。
basis查询参数字符串否已存的最佳来源own、third_party 或 partner_reported。按名称指定一个来源,并跳过顺序。某个来源对该问题没有数据时返回 404 basis_not_available。
currency查询参数字符串否来源自己的货币USD。用每个月的每日平均汇率换算。
top查询参数整数否全部数据行1 至 1000。保留每个月、每个流向中最大的 N 个国家行,按数值排序,数值相同时按伙伴国代码决定先后,并给每行加上 rank。组行和未分配行不排名。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
share查询参数布尔值否falsetrue 为每行加上 share:其数值除以同一月份、同一流向的国家行之和,以 1 的小数表示,保留 6 位小数。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
ytd查询参数布尔值否falsetrue 把一月至 end(默认:最新月份)已存的各月份求和,period_type 为 year_to_date。请发送 end 而不是 start:带 start 的请求返回 400。缺少某个月份返回 404 period_not_published。计算所得。不适用于伙伴国报告的响应。
change查询参数布尔值否falsetrue 为每行加上 change:一年前的同一个月(或年初至今),以及差额和双方的发布状态。缺少一年前的月份返回 404 period_not_published。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。
include_groups查询参数布尔值否falsetrue 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。
limit查询参数整数否5001 至 1000。一页最多返回的数据行数。
cursor查询参数字符串否无上一页的 next_cursor,其他所有参数保持不变。

响应

响应包含伙伴国路由中列出的字段(见该页),以及以下三个关于产品的字段。totals 含该产品的总额,即其所有页中各行之和,official_total 为 null。

字段含义
product_code所请求的 HS 编码。
product_level2 表示章,4 表示品目,6 表示子目。
product_label编码的名称。对于不是 HS 产品的行为 null,例如智利发布机构的剩余编码 999999,其响应仍含数据行。

rows 的每一项是一个伙伴国在一个月、一个流向上的数据,字段与伙伴国路由相同。

字段含义
flowexport 或 import。
period月份,YYYY-MM。对于年初至今,为其最后一个月。
period_typemonth 或 year_to_date。
period_start, period_end该行所涵盖的第一天和最后一天,YYYY-MM-DD。
valuecurrency 货币的整数单位,为十进制字符串。
net_weight_kg净重,以千克计,为十进制字符串,发布机构提供时才有。否则为 null。
rank带 top 时:该行的排名,最大者为 1。否则为 null。
share带 share 时:该行占总额的比例,保留 6 位小数。否则为 null。
change带 change 时:一个对象,含 previous_period、previous_value、absolute(数值减去上期数值)、percent(以百分数表示,保留 4 位小数,前值为 0 时为 null)、release_status 和 previous_release_status(preliminary、revised、final,发布机构未说明时为 null)。一年前的行不存在或未请求 change 时为 null。
partner伙伴国的 ISO 3166-1 alpha-3 代码、EUU 这样的组代码,或没有国家的行为空。
partner_label发布机构自己使用的伙伴国名称。
partner_kindcountry、group 或 unallocated。
unallocated_reason对于未分配行:not_specified、confidential、stores_bunkers、free_zone、other 或 rest。否则为 null。

更多示例

版本中没有的编码

既没有名称也没有数据行的 HS 编码返回 404,且免费:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/999999?start=2026-06&end=2026-06&flow=export&limit=3"
英国,编码 999999
{
  "type": "https://narwhalapi.com/problems/hs-code-not-found",
  "title": "HS code not found",
  "status": 404,
  "detail": "HS 2022 has no code 999999.",
  "code": "hs_code_not_found",
  "request_id": "16a6db4e-d5d6-45ee-954b-4512cf137e63"
}

来源

每个请求由一个来源提供数据,即按以下顺序第一个存有数据行的来源:该国自己的海关或统计机构(basis 为 own)、该国向 UN Comtrade 的申报(third_party,仅伙伴国总额),然后是其他国家对该国的报告,进出口流向互换(partner_reported)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时,UN Comtrade 没有数据,所以顺序是 own,然后是 partner_reported,且 partner_reported 只到章(2 位)。basis 用于按名称指定一个来源。响应中的 basis、source 和 note 字段说明由哪个来源提供数据,同一响应绝不混用多个来源。伙伴国报告的响应与该国自己的数据是不同的计量,绝不是官方数据。伙伴国报告的响应只到章,因此对本国机构只提供伙伴国总额的国家,4 位或 6 位的编码返回 404 basis_not_available。

币种

数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币,例如英国税务海关总署(HM Revenue & Customs)为 GBP。currency=USD 用当月每日汇率的平均值换算每个月。每个月所用的汇率列在 fx 中,calculated 列出被换算的字段。没有汇率的月份返回 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参数缺失、格式错误或超出允许取值,例如 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。
404country_not_coveredNarwhal 在任何来源中都没有该国的贸易数据行。
404period_not_published所查询的月份未存入(No trade rows for 2026-10.),或 ytd 或 change 所需的某个月份缺失。
404basis_not_available所指定的来源,或顺序中的每个来源,对该问题都没有数据。detail 说明原因,例如该国自己的机构只提供伙伴国总额而不提供产品,或伙伴国报告的响应只到章(2 位),或泰国自己的机构只保存 4 位而请求了 6 位。见覆盖范围路由。
404hs_code_not_foundHS 版本中没有该编码的名称,且该国没有它的数据行,例如英国和编码 999999 返回 HS 2022 has no code 999999. 该国文件中确有、但没有名称的编码(发布机构的剩余行)返回 200,product_label 为 null。
404rate_not_available请求了 currency=USD,但某个月份没有汇率。
503upstream_unavailable汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。
503trade_data_unavailable目前无法读取产品文件。请稍后重试。

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

此页面对你有帮助吗?