1品目貿易APIリファレンス
1つの国の1つのHSコードの輸出入を、全パートナー国について読み取ります。パートナー国、月、方向ごとに1行で、コードの名称が付きます。
概要
GET /
GET / は、1つの国の1つのHSコードの貿易を全パートナー国について返します。パートナー国、月、方向ごとに1行で、コードの名称が付きます。hs は2桁、4桁、6桁のコードです。
どのパートナー国がその品目を買い、または売っているかを調べるために使います。パートナー国ルートと同じオプションを受け付け、hs を指定したパートナー国のリクエストは同じ数値を返します。
HS版にないコードには、404 hs_ が返ります。MCPツールは trade_ で、同じパラメータを受け付けます。
リクエスト
2026年6月の英国と米国の間の項8517(電話機その他のデータ送受信用機器)と、実際のレスポンス:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products/8517?partner=USA&start=2026-06&end=2026-06"{
"country": "GBR",
"basis": "own",
"source": "HM Revenue & Customs",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "GBP",
"classification": "HS",
"edition": "2022",
"edition_basis": "inferred_from_year",
"valuation_basis": "not_stated",
"trade_system": "not_stated",
"partner_basis": "not_stated",
"trade_scope": "all_partners",
"latest_period": "2026-09",
"total_basis": "customs",
"totals": [
{
"period": "2026-06",
"flow": "export",
"official_total": null,
"sum_of_rows": "46135455"
},
{
"period": "2026-06",
"flow": "import",
"official_total": null,
"sum_of_rows": "89090099"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 2,
"product_code": "8517",
"product_level": 4,
"product_label": "Telephone sets, incl. telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, incl. apparatus for communication in a wired or wireless network [such as a local or wide area network]; parts thereof (excl. than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528)",
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "46135455",
"net_weight_kg": "74435",
"rank": null,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "89090099",
"net_weight_kg": "246068",
"rank": null,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}方向ごとに1行あります。totals は米国との項8517の合計、つまり2行の合計を保持し、公表元は1つの品目の合計を表示しないため、official_ は null です。
パラメータ
| パラメータ | 場所 | 種別 | 必須 | デフォルト | 許容値と意味 |
|---|---|---|---|---|---|
country | パス | 文字列 | はい | なし | 報告国のISO 3166-1 alpha-3コード(大文字)。例:GBR。国ではないコードには400が返ります。数値のない国には404 country_ が返ります。 |
hs | パス | 文字列 | はい | なし | 2桁、4桁、6桁のHSコード。例:85、8517、851713。他の桁数には400が返ります。HS版に名称がなく、その国の行もないコードには、404 hs_ が返ります。タイは4桁で保有しているため、タイに6桁のコードを指定すると404 basis_ が返ります。 |
partner | クエリ | 文字列 | いいえ | すべてのパートナー国 | 1つのパートナー国のISO 3166-1 alpha-3コード(大文字)。その国のパートナー国ではないコードには、400 unknown_ が返ります。 |
flow | クエリ | 文字列 | いいえ | 両方向 | export または import。 |
start | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最初の月(含む)。start のみで end がない場合、回答は保有する最新の月までです。start が end より後の場合は400が返ります。 |
end | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最後の月(含む)。end のみの場合、回答はそれ以前で保有する最新の月です。 |
basis | クエリ | 文字列 | いいえ | 保有する最良のソース | own、third_、partner_。ソースを名前で1つ指定し、順序をスキップします。問い合わせに該当する行がないソースには、404 basis_ が返ります。 |
currency | クエリ | 文字列 | いいえ | ソース自身の通貨 | USD。各月を日次レートの平均で換算します。 |
top | クエリ | 整数 | いいえ | すべての行 | 1〜1000。各月・各方向について、値の大きい順に上位N行の国の行を残し、同順位はパートナー国コードで決め、各行に rank を追加します。グループ行と未配分行には順位をつけません。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
share | クエリ | ブール値 | いいえ | false | true を指定すると、各行に share を追加します。同じ月と方向の国の行の合計に対するその行の値を、小数点以下6桁の1に対する割合で表します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
ytd | クエリ | ブール値 | いいえ | false | true を指定すると、1月から end(デフォルトは最新の月)までを保存済みの月から合算し、period_ は year_ になります。start ではなく end を送ってください。start を指定すると400が返ります。月が欠けている場合は404 period_ が返ります。算出値です。パートナー国報告の回答には使えません。 |
change | クエリ | ブール値 | いいえ | false | true を指定すると、各行に change を追加します。1年前の同じ月(または年初来)と、その差、および両側の公表状況を示します。1年前の月が欠けている場合は404 period_ が返ります。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
include_ | クエリ | ブール値 | いいえ | false | true を指定すると、EUやASEANなど、公表元が表示するグループ行も返します。グループ行は、合計、順位、構成比には含まれません。 |
limit | クエリ | 整数 | いいえ | 500 | 1〜1000。1ページの最大行数。 |
cursor | クエリ | 文字列 | いいえ | なし | 前のページの next_。他のパラメータは変更しません。 |
レスポンス
回答には、パートナー国ルートのフィールド(そのページに掲載)と、品目についての次の3つがあります。totals はその品目の合計、すなわち全ページの行の合計を保持し、official_ は null です。
| フィールド | 意味 |
|---|---|
product_ | 求められたHSコード。 |
product_ | 類は 2、項は 4、号は 6。 |
product_ | コードの名称。HS品目ではない行では null。例:チリの公表元の残余コード 999999(行つきで回答されます)。 |
rows の各項目は、1つのパートナー国の、1つの月と方向で、パートナー国ルートと同じフィールドを持ちます。
| フィールド | 意味 |
|---|---|
flow | export または import。 |
period | 月(YYYY-MM)。年初来の場合は、その最後の月。 |
period_ | month または year_。 |
period_ | その行が対象とする最初の日と最後の日(YYYY-MM-DD)。 |
value | currency の整数単位。小数の文字列です。 |
net_ | 公表元が提供している場合の、キログラム単位の正味重量。小数の文字列です。それ以外は null。 |
rank | top を指定した場合:その行の順位。最大が1。それ以外は null。 |
share | share を指定した場合:合計に対するその行の割合。小数点以下6桁。それ以外は null。 |
change | change を指定した場合:previous_、previous_、absolute(値から前回の値を引いたもの)、percent(パーセント、小数点以下4桁、以前の値が0の場合は null)、release_、previous_(preliminary、revised、final、公表元が示していない場合は null)を持つオブジェクト。1年前の行が存在しない場合、または change を求めていない場合は null。 |
partner | パートナー国のISO 3166-1 alpha-3コード、EUU などのグループコード、または国のない行では空。 |
partner_ | パートナー国の、公表元自身による名称。 |
partner_ | country、group、unallocated。 |
unallocated_ | 未配分の行の場合:not_、confidential、stores_、free_、other、rest。それ以外は null。 |
その他の例
版にないコード
名称も行もないHSコードには、404が返り、無料です:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products/999999?start=2026-06&end=2026-06&flow=export&limit=3"{
"type": "https://narwhalapi.com/problems/hs-code-not-found",
"title": "HS code not found",
"status": 404,
"detail": "HS 2022 has no code 999999.",
"code": "hs_code_not_found",
"request_id": "16a6db4e-d5d6-45ee-954b-4512cf137e63"
}ソース
各リクエストには1つのソースが回答します。この順序で、行を保有する最初のソースです。その国自身の税関または統計機関(basis は own)、その国自身のUN Comtradeへの申告(third_、パートナー国の合計のみ)、次に、その国について他国が報告した内容で方向を入れ替えたもの(partner_)。他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_ で、partner_ は類(2桁)までしか届きません。basis はソースを名前で1つ求めます。回答の basis、source、note フィールドが、どのソースが回答したかを示し、ソースが1つの回答の中で混在することはありません。パートナー国報告の回答は、その国自身の数値とは別の測定であり、公式の数値ではありません。パートナー国報告の回答は類までしか届かないため、その国自身の機関がパートナー国の合計のみを提供する国では、4桁または6桁のコードに404 basis_ が返ります。
通貨
値は currency に示される通貨の整数単位で、小数の文字列で表されます。デフォルトでは、ソースが公表している通貨です。例:英国歳入関税庁(HM Revenue & Customs)ではGBP。currency=USD は、各月をその月の日次為替レートの平均で換算します。月ごとに使用したレートは fx に挙がり、calculated が換算したフィールドを示します。レートのない月には404 rate_ が返ります。為替レートのソースが回答できない場合は、503 upstream_ が返ります。すでにUSDの回答は、そのまま返されます。
ページング
limit は1ページの最大行数を1〜1000で指定し、デフォルトは500です。さらに行が一致する場合、next_ に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_ が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。
価格
1行以上を返すリクエストは1回の呼び出しで、1,000回あたり$2です。長い回答の各ページは、limit にかかわらず1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料です。
エラー
これらのエラーは、request_ を含む共通のエラー形式で返されます。キーがない、または無効な場合(401)、残高が呼び出しの料金に満たない場合(402)、1分あたりのリクエストが多すぎる場合(429)は、すべてのルートに共通するアカウントのエラーです。APIエラーとクレジットを参照してください。
| ステータス | コード | 発生する場面 |
|---|---|---|
400 | invalid_query | パラメータが不足している、形式が不正、または許容値の範囲外の場合。例:start=2026-13、end より後の start、start と併せて送られた ytd、送られた as_ または version(これらのルートは現在保有している内容を返します)。パートナー国報告の回答に top、share、ytd、change を求めた場合も同様です。 |
400 | invalid_cursor | カーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。 |
400 | unknown_partner | partner が、指定した月においてその国のパートナー国ではない場合。例:ZZZ is not a partner of GBR. |
400 | range_too_large | top、share、ytd、change が12か月を超える場合、パートナー国報告の回答が12か月を超える場合、または、あらゆるレベル(2桁、4桁、6桁)の品目の回答が、hs も partner もなしに、保有する12か月を超える場合。オープンクエリは、12か月を超える期間を invalid_ として拒否します。 |
404 | country_not_covered | Narwhalは、どのソースにもその国の貿易の行を保有していません。 |
404 | period_not_published | 指定した月が保有されていない場合(No trade rows for 2026-10.)、または ytd や change に必要な月が欠けている場合。 |
404 | basis_not_available | 求められたソース、または順序内のすべてのソースが、その問い合わせに該当するものを何も保有していない場合。detail に理由が示されます。例:その国自身の機関がパートナー国の合計のみで品目を提供していない場合や、パートナー国報告の回答が類(2桁)までしか届かない場合や、タイ自身の機関が4桁で保有しているのに6桁を求められた場合。カバレッジルートを参照してください。 |
404 | hs_code_not_found | HS版にそのコードの名称がなく、その国もそのコードの行を保有していない場合。例:英国とコード 999999 には HS 2022 has no code 999999. が返ります。その国のファイルが保有しているが名称のないコード(公表元の残余行)には、200が返り、product_ は null です。 |
404 | rate_not_available | currency=USD が求められ、ある月の為替レートがない場合。 |
503 | upstream_unavailable | 為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。 |
503 | trade_data_unavailable | 品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。 |
このページは役に立ちましたか?