HSコード検索APIリファレンス
1つの版のHarmonized Systemコード(2桁、4桁、6桁)を、名称、レベル、親で検索または一覧表示します。
概要
GET /
GET / は、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_ で、同じパラメータを受け付けます。
リクエスト
2022年版で「cheese」を検索した例、最初のページ(3件)と、実際のレスポンス:
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"
}ページには3件のコードのうち最初の2件を示しています。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。1ページの最大コード数。 |
cursor | クエリ | 文字列 | いいえ | なし | 前のページの next_。他のパラメータは変更しません。 |
レスポンス
回答には次のフィールドがあります。
| フィールド | 意味 |
|---|---|
classification | HS。 |
edition | 一覧の版。 |
total | 全ページにわたる、一致するコードの数。 |
codes | このページのコード。それぞれ code、level(2、4、6)、label(その版の言葉による、コードの名称)、parent(1つ上のレベルのコード。類では 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ページの最大コード数を1〜1000で指定し、デフォルトは100です。さらにコードが一致する場合、next_ に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_ が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。
価格
1つ以上のコードを返す各リクエストは1回の呼び出しで、1,000回あたり$2です。長い一覧の各ページも1回の呼び出しです。一致のない検索は無料で、すべてのエラーも無料です。
エラー
これらのエラーは、request_ を含む共通のエラー形式で返されます。キーがない、または無効な場合(401)、残高が呼び出しの料金に満たない場合(402)、1分あたりのリクエストが多すぎる場合(429)は、すべてのルートに共通するアカウントのエラーです。APIエラーとクレジットを参照してください。
| ステータス | コード | 発生する場面 |
|---|---|---|
400 | invalid_query | edition、level、limit が許容値の範囲外の場合、q が2文字より短い場合、または parent が2桁、4桁、6桁のコードではない場合。 |
400 | invalid_cursor | カーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。 |
このページは役に立ちましたか?