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

1品目貿易APIリファレンス

1つの国の1つのHSコードの輸出入を、全パートナー国について読み取ります。パートナー国、月、方向ごとに1行で、コードの名称が付きます。

概要

GET /v1/trade/{country}/products/{hs}

GET /v1/trade/{country}/products/{hs} は、1つの国の1つのHSコードの貿易を全パートナー国について返します。パートナー国、月、方向ごとに1行で、コードの名称が付きます。hs は2桁、4桁、6桁のコードです。

どのパートナー国がその品目を買い、または売っているかを調べるために使います。パートナー国ルートと同じオプションを受け付け、hs を指定したパートナー国のリクエストは同じ数値を返します。

HS版にないコードには、404 hs_code_not_found が返ります。MCPツールは trade_get_product で、同じパラメータを受け付けます。

リクエスト

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"
英国、項8517、米国との貿易
{
  "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_total は null です。

パラメータ

パラメータ場所種別必須デフォルト許容値と意味
countryパス文字列はいなし報告国のISO 3166-1 alpha-3コード(大文字)。例:GBR。国ではないコードには400が返ります。数値のない国には404 country_not_covered が返ります。
hsパス文字列はいなし2桁、4桁、6桁のHSコード。例:85、8517、851713。他の桁数には400が返ります。HS版に名称がなく、その国の行もないコードには、404 hs_code_not_found が返ります。タイは4桁で保有しているため、タイに6桁のコードを指定すると404 basis_not_available が返ります。
partnerクエリ文字列いいえすべてのパートナー国1つのパートナー国のISO 3166-1 alpha-3コード(大文字)。その国のパートナー国ではないコードには、400 unknown_partner が返ります。
flowクエリ文字列いいえ両方向export または import。
startクエリ文字列、YYYY-MMいいえ保有する最新の月最初の月(含む)。start のみで end がない場合、回答は保有する最新の月までです。start が end より後の場合は400が返ります。
endクエリ文字列、YYYY-MMいいえ保有する最新の月最後の月(含む)。end のみの場合、回答はそれ以前で保有する最新の月です。
basisクエリ文字列いいえ保有する最良のソースown、third_party、partner_reported。ソースを名前で1つ指定し、順序をスキップします。問い合わせに該当する行がないソースには、404 basis_not_available が返ります。
currencyクエリ文字列いいえソース自身の通貨USD。各月を日次レートの平均で換算します。
topクエリ整数いいえすべての行1〜1000。各月・各方向について、値の大きい順に上位N行の国の行を残し、同順位はパートナー国コードで決め、各行に rank を追加します。グループ行と未配分行には順位をつけません。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
shareクエリブール値いいえfalsetrue を指定すると、各行に share を追加します。同じ月と方向の国の行の合計に対するその行の値を、小数点以下6桁の1に対する割合で表します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
ytdクエリブール値いいえfalsetrue を指定すると、1月から end(デフォルトは最新の月)までを保存済みの月から合算し、period_type は year_to_date になります。start ではなく end を送ってください。start を指定すると400が返ります。月が欠けている場合は404 period_not_published が返ります。算出値です。パートナー国報告の回答には使えません。
changeクエリブール値いいえfalsetrue を指定すると、各行に change を追加します。1年前の同じ月(または年初来)と、その差、および両側の公表状況を示します。1年前の月が欠けている場合は404 period_not_published が返ります。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
include_groupsクエリブール値いいえfalsetrue を指定すると、EUやASEANなど、公表元が表示するグループ行も返します。グループ行は、合計、順位、構成比には含まれません。
limitクエリ整数いいえ5001〜1000。1ページの最大行数。
cursorクエリ文字列いいえなし前のページの next_cursor。他のパラメータは変更しません。

レスポンス

回答には、パートナー国ルートのフィールド(そのページに掲載)と、品目についての次の3つがあります。totals はその品目の合計、すなわち全ページの行の合計を保持し、official_total は null です。

フィールド意味
product_code求められたHSコード。
product_level類は 2、項は 4、号は 6。
product_labelコードの名称。HS品目ではない行では null。例:チリの公表元の残余コード 999999(行つきで回答されます)。

rows の各項目は、1つのパートナー国の、1つの月と方向で、パートナー国ルートと同じフィールドを持ちます。

フィールド意味
flowexport または import。
period月(YYYY-MM)。年初来の場合は、その最後の月。
period_typemonth または year_to_date。
period_start, period_endその行が対象とする最初の日と最後の日(YYYY-MM-DD)。
valuecurrency の整数単位。小数の文字列です。
net_weight_kg公表元が提供している場合の、キログラム単位の正味重量。小数の文字列です。それ以外は null。
ranktop を指定した場合:その行の順位。最大が1。それ以外は null。
shareshare を指定した場合:合計に対するその行の割合。小数点以下6桁。それ以外は null。
changechange を指定した場合:previous_period、previous_value、absolute(値から前回の値を引いたもの)、percent(パーセント、小数点以下4桁、以前の値が0の場合は null)、release_status、previous_release_status(preliminary、revised、final、公表元が示していない場合は null)を持つオブジェクト。1年前の行が存在しない場合、または change を求めていない場合は null。
partnerパートナー国のISO 3166-1 alpha-3コード、EUU などのグループコード、または国のない行では空。
partner_labelパートナー国の、公表元自身による名称。
partner_kindcountry、group、unallocated。
unallocated_reason未配分の行の場合:not_specified、confidential、stores_bunkers、free_zone、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"
英国、コード999999
{
  "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_party、パートナー国の合計のみ)、次に、その国について他国が報告した内容で方向を入れ替えたもの(partner_reported)。他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_reported で、partner_reported は類(2桁)までしか届きません。basis はソースを名前で1つ求めます。回答の basis、source、note フィールドが、どのソースが回答したかを示し、ソースが1つの回答の中で混在することはありません。パートナー国報告の回答は、その国自身の数値とは別の測定であり、公式の数値ではありません。パートナー国報告の回答は類までしか届かないため、その国自身の機関がパートナー国の合計のみを提供する国では、4桁または6桁のコードに404 basis_not_available が返ります。

通貨

値は currency に示される通貨の整数単位で、小数の文字列で表されます。デフォルトでは、ソースが公表している通貨です。例:英国歳入関税庁(HM Revenue & Customs)ではGBP。currency=USD は、各月をその月の日次為替レートの平均で換算します。月ごとに使用したレートは fx に挙がり、calculated が換算したフィールドを示します。レートのない月には404 rate_not_available が返ります。為替レートのソースが回答できない場合は、503 upstream_unavailable が返ります。すでにUSDの回答は、そのまま返されます。

ページング

limit は1ページの最大行数を1〜1000で指定し、デフォルトは500です。さらに行が一致する場合、next_cursor に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_cursor が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。

価格

1行以上を返すリクエストは1回の呼び出しで、1,000回あたり$2です。長い回答の各ページは、limit にかかわらず1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料です。

エラー

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

ステータスコード発生する場面
400invalid_queryパラメータが不足している、形式が不正、または許容値の範囲外の場合。例:start=2026-13、end より後の start、start と併せて送られた ytd、送られた as_of または version(これらのルートは現在保有している内容を返します)。パートナー国報告の回答に top、share、ytd、change を求めた場合も同様です。
400invalid_cursorカーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。
400unknown_partnerpartner が、指定した月においてその国のパートナー国ではない場合。例:ZZZ is not a partner of GBR.
400range_too_largetop、share、ytd、change が12か月を超える場合、パートナー国報告の回答が12か月を超える場合、または、あらゆるレベル(2桁、4桁、6桁)の品目の回答が、hs も partner もなしに、保有する12か月を超える場合。オープンクエリは、12か月を超える期間を invalid_query として拒否します。
404country_not_coveredNarwhalは、どのソースにもその国の貿易の行を保有していません。
404period_not_published指定した月が保有されていない場合(No trade rows for 2026-10.)、または ytd や change に必要な月が欠けている場合。
404basis_not_available求められたソース、または順序内のすべてのソースが、その問い合わせに該当するものを何も保有していない場合。detail に理由が示されます。例:その国自身の機関がパートナー国の合計のみで品目を提供していない場合や、パートナー国報告の回答が類(2桁)までしか届かない場合や、タイ自身の機関が4桁で保有しているのに6桁を求められた場合。カバレッジルートを参照してください。
404hs_code_not_foundHS版にそのコードの名称がなく、その国もそのコードの行を保有していない場合。例:英国とコード 999999 には HS 2022 has no code 999999. が返ります。その国のファイルが保有しているが名称のないコード(公表元の残余行)には、200が返り、product_label は null です。
404rate_not_availablecurrency=USD が求められ、ある月の為替レートがない場合。
503upstream_unavailable為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。
503trade_data_unavailable品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。

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

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