すべてのドキュメントを閲覧

HSコード検索APIリファレンス

1つの版のHarmonized Systemコード(2桁、4桁、6桁)を、名称、レベル、親で検索または一覧表示します。

概要

GET /v1/trade/hs-codes

GET /v1/trade/hs-codes は、1つの版のHarmonized System(HS)コードを一覧表示します。HSコードは取引される物を表し、2桁は類、4桁は項、6桁は号です。貿易ルートはこれらのコードを返し、このルートは必要なコードを見つけます。

q は名称を検索します。類が先、次に項、次に号の順で、各レベルの中では最もよく一致するものが先に来ます。parent はコードの子を一覧表示し、level は1つの桁数に絞ります。4つの版は2007、2012、2017、2022です。版は相互に変換されないため、2022年に現れたコードは2017年の一覧にはありません。2022年版には96の類、1,228の項、5,612の号があります。MCPツールは trade_list_hs_codes で、同じパラメータを受け付けます。

リクエスト

2022年版で「cheese」を検索した例、最初のページ(3件)と、実際のレスポンス:

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"
}

ページには3件のコードのうち最初の2件を示しています。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。1ページの最大コード数。
cursorクエリ文字列いいえなし前のページの next_cursor。他のパラメータは変更しません。

レスポンス

回答には次のフィールドがあります。

フィールド意味
classificationHS。
edition一覧の版。
total全ページにわたる、一致するコードの数。
codesこのページのコード。それぞれ code、level(2、4、6)、label(その版の言葉による、コードの名称)、parent(1つ上のレベルのコード。類では 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ページの最大コード数を1〜1000で指定し、デフォルトは100です。さらにコードが一致する場合、next_cursor に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_cursor が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。

価格

1つ以上のコードを返す各リクエストは1回の呼び出しで、1,000回あたり$2です。長い一覧の各ページも1回の呼び出しです。一致のない検索は無料で、すべてのエラーも無料です。

エラー

これらのエラーは、request_id を含む共通のエラー形式で返されます。キーがない、または無効な場合(401)、残高が呼び出しの料金に満たない場合(402)、1分あたりのリクエストが多すぎる場合(429)は、すべてのルートに共通するアカウントのエラーです。APIエラーとクレジットを参照してください。

ステータスコード発生する場面
400invalid_queryedition、level、limit が許容値の範囲外の場合、q が2文字より短い場合、または parent が2桁、4桁、6桁のコードではない場合。
400invalid_cursorカーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。

APIエラーとクレジット · 貿易データAPIリファレンス · 貿易の対象国

このページは役に立ちましたか?