瀏覽全部文件

HS 代碼搜尋 API 參考

依名稱、層級或上層代碼,搜尋或列出某個版本的調和制度(Harmonized System)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 之前,因為品目的排序高於子目。

參數

參數位置類型必填預設值允許值與意義
qquery字串,2 至 100 個字元否無要在代碼名稱中尋找的文字。
editionquery字串否20222007、2012、2017 或 2022。其他任何值會回傳 400。
levelquery整數否所有層級2、4 或 6。僅限此位數的代碼。
parentquery字串否無2、4 或 6 位碼的 HS 代碼。僅限此代碼的下層代碼。章與品目有下層代碼,子目則沒有。
limitquery整數否1001 至 1000。單頁最多的代碼數。
cursorquery字串否無上一頁的 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),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。

狀態代碼發生時機
400invalid_queryedition、level 或 limit 超出允許值、q 短於 2 個字元,或 parent 不是 2、4 或 6 位碼的代碼。
400invalid_cursor此游標不是該請求所回傳的游標,或其後有其他參數已變更。

API 錯誤 處理:錯誤碼、額度與重試 · 貿易數據 API 參考 · 貿易國家

此頁面對你有幫助嗎?