单个产品贸易 API 参考
读取一个国家一个 HS 编码与每个伙伴国的进出口,每个伙伴国、每个月、每个流向一行,并附上该编码的名称。
概览
GET /
GET / 返回一个国家某个 HS 编码与每个伙伴国的贸易:每个伙伴国、每个月、每个流向一行,并附上该编码的名称。hs 是 2、4 或 6 位的编码。
用它了解哪些伙伴国买入或卖出某个产品。它的选项与伙伴国路由相同,带 hs 的伙伴国请求返回相同的数据。
HS 版本中没有的编码返回 404 hs_。MCP 工具是 trade_,参数相同。
请求
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"{
"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_ 为 null,因为发布机构不为单个产品列出总额。
参数
| 参数 | 位置 | 类型 | 必填 | 默认值 | 允许的取值及含义 |
|---|---|---|---|---|---|
country | 路径参数 | 字符串 | 是 | 无 | 报告国的 ISO 3166-1 alpha-3 代码,大写,例如 GBR。不是国家的代码返回 400。没有数据的国家返回 404 country_。 |
hs | 路径参数 | 字符串 | 是 | 无 | 2、4 或 6 位的 HS 编码,例如 85、8517 或 851713。其他位数返回 400。在 HS 版本中没有名称且该国没有数据行的编码返回 404 hs_。泰国按 4 位保存,因此对泰国使用 6 位编码返回 404 basis_。 |
partner | 查询参数 | 字符串 | 否 | 全部伙伴国 | 一个伙伴国的 ISO 3166-1 alpha-3 代码,大写。不是该国伙伴国的代码返回 400 unknown_。 |
flow | 查询参数 | 字符串 | 否 | 两个流向 | export 或 import。 |
start | 查询参数 | 字符串,YYYY-MM | 否 | 已存的最新月份 | 起始月份,含当月。有 start 而没有 end 时,响应截至已存的最新月份。start 晚于 end 返回 400。 |
end | 查询参数 | 字符串,YYYY-MM | 否 | 已存的最新月份 | 结束月份,含当月。只有 end 时,响应是不晚于它的已存最新月份。 |
basis | 查询参数 | 字符串 | 否 | 已存的最佳来源 | own、third_ 或 partner_。按名称指定一个来源,并跳过顺序。某个来源对该问题没有数据时返回 404 basis_。 |
currency | 查询参数 | 字符串 | 否 | 来源自己的货币 | USD。用每个月的每日平均汇率换算。 |
top | 查询参数 | 整数 | 否 | 全部数据行 | 1 至 1000。保留每个月、每个流向中最大的 N 个国家行,按数值排序,数值相同时按伙伴国代码决定先后,并给每行加上 rank。组行和未分配行不排名。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
share | 查询参数 | 布尔值 | 否 | false | true 为每行加上 share:其数值除以同一月份、同一流向的国家行之和,以 1 的小数表示,保留 6 位小数。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
ytd | 查询参数 | 布尔值 | 否 | false | true 把一月至 end(默认:最新月份)已存的各月份求和,period_ 为 year_。请发送 end 而不是 start:带 start 的请求返回 400。缺少某个月份返回 404 period_。计算所得。不适用于伙伴国报告的响应。 |
change | 查询参数 | 布尔值 | 否 | false | true 为每行加上 change:一年前的同一个月(或年初至今),以及差额和双方的发布状态。缺少一年前的月份返回 404 period_。计算所得。最多涵盖 12 个月。不适用于伙伴国报告的响应。 |
include_ | 查询参数 | 布尔值 | 否 | false | true 同时返回发布机构列出的组行,例如欧盟或东盟。组行从不计入求和、排名或占比。 |
limit | 查询参数 | 整数 | 否 | 500 | 1 至 1000。一页最多返回的数据行数。 |
cursor | 查询参数 | 字符串 | 否 | 无 | 上一页的 next_,其他所有参数保持不变。 |
响应
响应包含伙伴国路由中列出的字段(见该页),以及以下三个关于产品的字段。totals 含该产品的总额,即其所有页中各行之和,official_ 为 null。
| 字段 | 含义 |
|---|---|
product_ | 所请求的 HS 编码。 |
product_ | 2 表示章,4 表示品目,6 表示子目。 |
product_ | 编码的名称。对于不是 HS 产品的行为 null,例如智利发布机构的剩余编码 999999,其响应仍含数据行。 |
rows 的每一项是一个伙伴国在一个月、一个流向上的数据,字段与伙伴国路由相同。
| 字段 | 含义 |
|---|---|
flow | export 或 import。 |
period | 月份,YYYY-MM。对于年初至今,为其最后一个月。 |
period_ | month 或 year_。 |
period_ | 该行所涵盖的第一天和最后一天,YYYY-MM-DD。 |
value | currency 货币的整数单位,为十进制字符串。 |
net_ | 净重,以千克计,为十进制字符串,发布机构提供时才有。否则为 null。 |
rank | 带 top 时:该行的排名,最大者为 1。否则为 null。 |
share | 带 share 时:该行占总额的比例,保留 6 位小数。否则为 null。 |
change | 带 change 时:一个对象,含 previous_、previous_、absolute(数值减去上期数值)、percent(以百分数表示,保留 4 位小数,前值为 0 时为 null)、release_ 和 previous_(preliminary、revised、final,发布机构未说明时为 null)。一年前的行不存在或未请求 change 时为 null。 |
partner | 伙伴国的 ISO 3166-1 alpha-3 代码、EUU 这样的组代码,或没有国家的行为空。 |
partner_ | 发布机构自己使用的伙伴国名称。 |
partner_ | country、group 或 unallocated。 |
unallocated_ | 对于未分配行:not_、confidential、stores_、free_、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"{
"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_,仅伙伴国总额),然后是其他国家对该国的报告,进出口流向互换(partner_)。只有当至少 200 个报告国有关于该国的数据行时,其他国家的报告才会排在 UN Comtrade 之前,而这超过了 Narwhal 存有的数量,因此它们排在最后。按产品划分时,UN Comtrade 没有数据,所以顺序是 own,然后是 partner_,且 partner_ 只到章(2 位)。basis 用于按名称指定一个来源。响应中的 basis、source 和 note 字段说明由哪个来源提供数据,同一响应绝不混用多个来源。伙伴国报告的响应与该国自己的数据是不同的计量,绝不是官方数据。伙伴国报告的响应只到章,因此对本国机构只提供伙伴国总额的国家,4 位或 6 位的编码返回 404 basis_。
币种
数值是 currency 中所列货币的整数单位,写作十进制字符串。默认是来源发布时使用的货币,例如英国税务海关总署(HM Revenue & Customs)为 GBP。currency=USD 用当月每日汇率的平均值换算每个月。每个月所用的汇率列在 fx 中,calculated 列出被换算的字段。没有汇率的月份返回 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 | 参数缺失、格式错误或超出允许取值,例如 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 | 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 | hs_code_not_found | HS 版本中没有该编码的名称,且该国没有它的数据行,例如英国和编码 999999 返回 HS 2022 has no code 999999. 该国文件中确有、但没有名称的编码(发布机构的剩余行)返回 200,product_ 为 null。 |
404 | rate_not_available | 请求了 currency=USD,但某个月份没有汇率。 |
503 | upstream_unavailable | 汇率来源无法响应。这会影响 currency=USD 以及需要换算的伙伴国报告的响应。请稍后重试。 |
503 | trade_data_unavailable | 目前无法读取产品文件。请稍后重试。 |
此页面对你有帮助吗?