浏览全部文档

按产品划分的贸易 API 参考

读取一个国家按 2、4 或 6 位 HS 产品划分的进出口,每个编码、每个月、每个流向一行,并附上每个编码的名称。

概览

GET /v1/trade/{country}/products

GET /v1/trade/{country}/products 返回一个国家按产品划分的货物贸易:每个 HS 编码、每个月、每个流向一行,并附上编码名称。level 选择深度:2 为章(默认),4 为品目,6 为子目。不带 start 和 end 时,响应是已存的最新月份。

partner 把响应限定为一个伙伴国,hs 限定为以这些数字开头的编码。用它了解一个国家卖出和买入什么。一个产品对应每个伙伴国请用单个产品路由。

在一个国家的本国机构只提供伙伴国总额的情况下(加拿大、墨西哥和澳大利亚),产品路由根据其他国家的报告提供章的数据,标记为 partner_reported,对品目和子目则返回 404 basis_not_available。MCP 工具是 trade_get_products,参数相同。

请求

2026 年 6 月英国三大出口章及其占比,以及真实响应:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?start=2026-06&end=2026-06&flow=export&top=3&share=true"
英国,三大出口章
{
  "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": "37649508686",
      "sum_of_rows": "37649508686"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows",
    "rank",
    "share"
  ],
  "total": 3,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7115661421",
      "net_weight_kg": "195511199",
      "rank": 1,
      "share": "0.188997",
      "change": null,
      "product_code": "84",
      "product_level": 2,
      "product_label": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES; PARTS THEREOF",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7044982137",
      "net_weight_kg": "1706268",
      "rank": 2,
      "share": "0.187120",
      "change": null,
      "product_code": "71",
      "product_level": 2,
      "product_label": "NATURAL OR CULTURED PEARLS, PRECIOUS OR SEMI-PRECIOUS STONES, PRECIOUS METALS, METALS CLAD WITH PRECIOUS METAL, AND ARTICLES THEREOF; IMITATION JEWELLERY; COIN",
      "edition": "2022"
    }
  ],
  "next_cursor": null
}

页面显示三行中的前两行。share 是 1 的一个分数:84 章占该月出口的 0.189134。partner 为 null,因为各行没有限定为一个伙伴国。

参数

参数位置类型必填默认值允许的取值及含义
country路径参数字符串是无报告国的 ISO 3166-1 alpha-3 代码,大写,例如 GBR。不是国家的代码返回 400。没有数据的国家返回 404 country_not_covered。
level查询参数整数否22(章)、4(品目)或 6(子目)。其他任何值返回 400。泰国按 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 时,响应是不晚于它的已存最新月份。
hs查询参数字符串,1 至 6 位数字否全部编码只取以这些数字开头的编码。比 level 更长返回 400。
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 个月。不适用于伙伴国报告的响应。
limit查询参数整数否5001 至 1000。一页最多返回的数据行数。
cursor查询参数字符串否无上一页的 next_cursor,其他所有参数保持不变。

响应

响应包含伙伴国路由中列出的字段(见该页),另有一个与伙伴国筛选有关的字段。

字段含义
country响应所针对的报告国的 ISO 3166-1 alpha-3 代码。
partner各行所限定的伙伴国,未发送 partner 时为 null。
basis提供数据的来源:own、third_party(UN Comtrade)或 partner_reported。
source发布机构,例如 HM Revenue & Customs、Eurostat Comext、UN Comtrade 或 Customs reports of other countries。
reporters_included对于 partner_reported:其报告被互换后纳入响应的报告国的 count 和 countries。其他来源为 null。
note使用数据前请先阅读。伙伴国报告的响应会设置此项,其他情况为 null。
coveragefull 或 partial。伙伴国报告的响应为 partial。
partner_coverage列出所有伙伴国时为 all,发布机构只列出其主要伙伴国和一个“其余”行时为 top_n。伙伴国报告的响应为 null。
scopegoods。
currency响应中所有数值的 ISO 4217 代码。
classificationHS,即协调制度。
edition一个版本涵盖所查询的每个月份时的 HS 版本(2007、2012、2017 或 2022)。各月份不同时为 null,此时每一行注明各自的版本。
edition_basis发布机构说明版本时为 as_published,Narwhal 根据年份推断时为 inferred_from_year。
valuation_basis发布机构如何对贸易估价,例如出口按离岸价(FOB)、进口按到岸价(CIF)。未说明时为 not_stated。
trade_system发布机构有说明时为 general 或 special。否则为 not_stated。
partner_basis伙伴国按原产地、起运地还是目的地统计,以发布机构的说明为准。否则为 not_stated。
trade_scope数据所涵盖的内容,例如 all_partners、extra_union_only 或 intra_union_other_method。
latest_periodNarwhal 存有的该国该来源的最新月份。
total_basisofficial_total 的口径:customs、balance_of_payments 或 eurostat_concept。发布机构不提供总额时为 null。
totals每个月、每个流向一项:period、flow、official_total(发布机构自己的货物总额,没有时为 null)和 sum_of_rows(该月该流向除组行外所有伙伴国行之和,计算所得)。不带 hs 时,它是该月的全部货物总额,即使 partner 限定了行也是如此。带 hs 时(以及在单个产品路由上),它改为该产品的总额:sum_of_rows 是响应所有页中各行之和(若指定了 partner,则为该伙伴国的行;top 和分页不会削减它),official_total 为 null,因为发布机构不为单个产品列出总额。
fx带 currency=USD 时,以及伙伴国报告的响应含多种货币时:每个月所用的汇率,含 period、from_currency、to_currency、rate 和平均所含的 days。其他情况为 null。
calculatedNarwhal 计算的字段名称,例如 sum_of_rows、rank、share、value 或 official_total。
total所有页中匹配的行数。
next_cursor下一页的游标。最后一页为 null。

rows 的每一项是一个 HS 编码在一个月、一个流向上的数据。

字段含义
flowexport 或 import。
period月份,YYYY-MM。对于年初至今,为其最后一个月。
period_typemonth 或 year_to_date。
period_start, period_end该行所涵盖的第一天和最后一天,YYYY-MM-DD。
valuecurrency 货币的整数单位,为十进制字符串。
net_weight_kg净重,以千克计,发布机构提供时才有。否则为 null。
rank, share, change同伙伴国路由:带 top、share 和 change 时设置,否则为 null。
product_codeHS 编码,2、4 或 6 位。发布机构自己的、不是 HS 产品的行沿用发布机构的编码,例如表示船舶供应品和私人运送货物的 00。
product_level2 表示章,4 表示品目,6 表示子目。
product_label编码的名称。对于不是 HS 产品的行为 null。
edition该月份来源所用的 HS 版本。报告国使用不同版本时为 null。

更多示例

一个品目下的子目

英国出口中 8517 品目下的六位编码,第一页(五行):

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?level=6&hs=8517&start=2026-06&end=2026-06&flow=export&limit=5"
英国,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": "427312411"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 9,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "2578425",
      "net_weight_kg": "12393",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851711",
      "product_level": 6,
      "product_label": "Line telephone sets with cordless handsets",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "105530961",
      "net_weight_kg": "115108",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851713",
      "product_level": 6,
      "product_label": "Smartphones for wireless networks",
      "edition": "2022"
    }
  ],
  "next_cursor": "eyJiIjoiY2hhbmdlPUZhbHNlfGNvdW50cnk9R0JSfGVuZD0yMDI2LTA2fGZsb3c9ZXhwb3J0fGhzPTg1MTd8bGV2ZWw9NnxzaGFyZT1GYWxzZXxzdGFydD0yMDI2LTA2fHl0ZD1GYWxzZSIsIm8iOjV9"
}

页面显示五行中的前两行。total 为 9,因此设置了 next_cursor。totals 含九个子目之和,official_total 为 null。

只提供伙伴国总额的国家的品目

加拿大的本国机构不提供产品数据。请求品目返回 404,且免费:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/products?level=4&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
加拿大,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; UN Comtrade is held as partner totals only, not by product; partner-reported products are held at chapter level only (level=2). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "5dd0f449-8c1e-4354-9af6-d8a76a5eefdd"
}

来源

每个请求由一个来源提供数据,即按以下顺序第一个存有数据行的来源:该国自己的海关或统计机构(basis 为 own)、该国向 UN Comtrade 的申报(third_party,仅伙伴国总额),然后是其他国家对该国的报告,进出口流向互换(partner_reported)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时,UN Comtrade 没有数据,所以顺序是 own,然后是 partner_reported,且 partner_reported 只到章(2 位)。basis 用于按名称指定一个来源。响应中的 basis、source 和 note 字段说明由哪个来源提供数据,同一响应绝不混用多个来源。伙伴国报告的响应与该国自己的数据是不同的计量,绝不是官方数据。发布机构自己的、不是 HS 产品的行,例如船舶供应品和私人运送货物,以发布机构的编码返回(章级别为 00,子目级别为 999999),product_label 为 null。HS 编码路由(/v1/trade/hs-codes)不认识这些编码,对它们返回 404。单个产品路由(/v1/trade/{country}/products/{hs})会连同数据行返回它们,product_label 为 null。

币种

数值是 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参数缺失、格式错误或超出允许取值,例如 level=3、start=2026-13、start 晚于 end、ytd 与 start 一起发送、hs 比 level 更长,或发送了 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 位。见覆盖范围路由。
404rate_not_available请求了 currency=USD,但某个月份没有汇率。
503upstream_unavailable汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。
503trade_data_unavailable目前无法读取产品文件。请稍后重试。

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

此页面对你有帮助吗?