HS 代碼搜尋 API 參考
依名稱、層級或上層代碼,搜尋或列出某個版本的調和制度(Harmonized System)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 | query | 字串,2 至 100 個字元 | 否 | 無 | 要在代碼名稱中尋找的文字。 |
edition | query | 字串 | 否 | 2022 | 2007、2012、2017 或 2022。其他任何值會回傳 400。 |
level | query | 整數 | 否 | 所有層級 | 2、4 或 6。僅限此位數的代碼。 |
parent | query | 字串 | 否 | 無 | 2、4 或 6 位碼的 HS 代碼。僅限此代碼的下層代碼。章與品目有下層代碼,子目則沒有。 |
limit | query | 整數 | 否 | 100 | 1 至 1000。單頁最多的代碼數。 |
cursor | query | 字串 | 否 | 無 | 上一頁的 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),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。
| 狀態 | 代碼 | 發生時機 |
|---|---|---|
400 | invalid_query | edition、level 或 limit 超出允許值、q 短於 2 個字元,或 parent 不是 2、4 或 6 位碼的代碼。 |
400 | invalid_cursor | 此游標不是該請求所回傳的游標,或其後有其他參數已變更。 |
此頁面對你有幫助嗎?