浏览全部文档

HS 编码搜索 API 参考

按名称、级别或上级,搜索或列出一个版本中 2、4 和 6 位的协调制度编码。

概览

GET /v1/trade/hs-codes

GET /v1/trade/hs-codes 列出一个版本的协调制度(HS)编码。HS 编码为所交易的货物命名:2 位是章,4 位是品目,6 位是子目。贸易路由返回这些编码,而本路由帮你找到所需的那一个。

q 搜索名称。章排在最前,然后是品目,再是子目,同一级别内最匹配的排在最前。parent 列出一个编码的下级,level 只保留一种位数。四个版本是 2007、2012、2017 和 2022。各版本之间从不相互转换,因此 2022 年新出现的编码不在 2017 年的列表中。2022 版有 96 个章、1,228 个品目和 5,612 个子目。MCP 工具是 trade_list_hs_codes,参数相同。

请求

在 2022 版中搜索 cheese(奶酪),第一页(三行),以及真实响应:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"
与 cheese(奶酪)匹配的编码
{
  "classification": "HS",
  "edition": "2022",
  "total": 6,
  "codes": [
    {
      "code": "0406",
      "level": 4,
      "label": "Cheese and curd",
      "parent": "04"
    },
    {
      "code": "040690",
      "level": 6,
      "label": "Cheese (excl. fresh cheese, incl. whey cheese, curd, processed cheese, blue-veined cheese and other cheese containing veins produced by \"Penicillium roqueforti\", and grated or powdered cheese)",
      "parent": "0406"
    }
  ],
  "next_cursor": "eyJiIjoiaHM6MjAyMjpjaGVlc2U6Tm9uZTpOb25lOjMiLCJvIjozfQ"
}

页面显示三个编码中的前两个。total 为 6,因此设置了 next_cursor。品目 0406 排在其子目 040690 之前,因为品目的排序高于子目。

参数

参数位置类型必填默认值允许的取值及含义
q查询参数字符串,2 至 100 个字符否无在编码名称中查找的文本。
edition查询参数字符串否20222007、2012、2017 或 2022。其他任何值返回 400。
level查询参数整数否全部级别2、4 或 6。只取这种位数的编码。
parent查询参数字符串否无2、4 或 6 位的 HS 编码。只取该编码的下级。章和品目有下级,子目没有。
limit查询参数整数否1001 至 1000。一页最多返回的编码数。
cursor查询参数字符串否无上一页的 next_cursor,其他所有参数保持不变。

响应

响应包含以下字段。

字段含义
classificationHS。
edition列表所属的版本。
total所有页中匹配的编码数。
codes此页的编码。每个含 code、level(2、4 或 6)、label(该版本用语中的编码名称)和 parent(上一级编码,章为 null)。
next_cursor下一页的游标。最后一页为 null。

更多示例

无匹配

没有匹配的搜索返回 200 和一个空列表,且免费:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes?q=zzzzqqq"
无匹配
{
  "classification": "HS",
  "edition": "2022",
  "total": 0,
  "codes": [],
  "next_cursor": null
}

来源

该路由列出编码,不存有贸易数据,因此不适用任何来源。

币种

该路由不返回数值,因此不适用货币。

分页

limit 设定一页最多返回的编码数,范围 1 至 1000,默认 100。匹配的编码多于一页时,next_cursor 含下一页的游标:将其作为 cursor 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_cursor。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。

价格

返回至少一个编码的每个请求算一次调用,每 1,000 次调用 $2,长列表的每一页也算一次调用。没有匹配的搜索免费,每个错误也免费。

错误

这些错误采用通用的错误响应格式,并带有 request_id。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。

状态代码触发时机
400invalid_queryedition、level 或 limit 超出允许取值,q 短于 2 个字符,或 parent 不是 2、4 或 6 位的编码。
400invalid_cursor游标不是此请求返回的,或者此后另一个参数已改变。

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

此页面对你有帮助吗?