HS 编码搜索 API 参考
按名称、级别或上级,搜索或列出一个版本中 2、4 和 6 位的协调制度编码。
概览
GET /
GET / 列出一个版本的协调制度(HS)编码。HS 编码为所交易的货物命名:2 位是章,4 位是品目,6 位是子目。贸易路由返回这些编码,而本路由帮你找到所需的那一个。
q 搜索名称。章排在最前,然后是品目,再是子目,同一级别内最匹配的排在最前。parent 列出一个编码的下级,level 只保留一种位数。四个版本是 2007、2012、2017 和 2022。各版本之间从不相互转换,因此 2022 年新出现的编码不在 2017 年的列表中。2022 版有 96 个章、1,228 个品目和 5,612 个子目。MCP 工具是 trade_,参数相同。
请求
在 2022 版中搜索 cheese(奶酪),第一页(三行),以及真实响应:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"{
"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_。品目 0406 排在其子目 040690 之前,因为品目的排序高于子目。
参数
| 参数 | 位置 | 类型 | 必填 | 默认值 | 允许的取值及含义 |
|---|---|---|---|---|---|
q | 查询参数 | 字符串,2 至 100 个字符 | 否 | 无 | 在编码名称中查找的文本。 |
edition | 查询参数 | 字符串 | 否 | 2022 | 2007、2012、2017 或 2022。其他任何值返回 400。 |
level | 查询参数 | 整数 | 否 | 全部级别 | 2、4 或 6。只取这种位数的编码。 |
parent | 查询参数 | 字符串 | 否 | 无 | 2、4 或 6 位的 HS 编码。只取该编码的下级。章和品目有下级,子目没有。 |
limit | 查询参数 | 整数 | 否 | 100 | 1 至 1000。一页最多返回的编码数。 |
cursor | 查询参数 | 字符串 | 否 | 无 | 上一页的 next_,其他所有参数保持不变。 |
响应
响应包含以下字段。
| 字段 | 含义 |
|---|---|
classification | HS。 |
edition | 列表所属的版本。 |
total | 所有页中匹配的编码数。 |
codes | 此页的编码。每个含 code、level(2、4 或 6)、label(该版本用语中的编码名称)和 parent(上一级编码,章为 null)。 |
next_ | 下一页的游标。最后一页为 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 发送,其他参数保持不变。来自其他请求的游标返回 400 invalid_。total 统计所有页中匹配的行数。MCP 工具一次结果最多返回 200 行。
价格
返回至少一个编码的每个请求算一次调用,每 1,000 次调用 $2,长列表的每一页也算一次调用。没有匹配的搜索免费,每个错误也免费。
错误
这些错误采用通用的错误响应格式,并带有 request_。缺少或无效的密钥(401)、余额低于一次调用的价格(402)以及每分钟请求过多(429)是所有路由共有的账户类错误:见 API 错误码与额度。
| 状态 | 代码 | 触发时机 |
|---|---|---|
400 | invalid_query | edition、level 或 limit 超出允许取值,q 短于 2 个字符,或 parent 不是 2、4 或 6 位的编码。 |
400 | invalid_cursor | 游标不是此请求返回的,或者此后另一个参数已改变。 |
此页面对你有帮助吗?