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

貿易データAPIリファレンス

Narwhalが保有する国については当該国の税関または統計機関から、それ以外の国についてはUN Comtradeまたは他国の報告から、パートナー国別・HS品目別の財貿易を月ごとに読み取ります。

概要

貿易データAPIは、パートナー国別・品目別の財貿易を1か月単位で返します。1行は、ある月における1つの方向(輸出または輸入)について、パートナー国または品目と、通貨の整数単位による値を示します。品目は2桁、4桁、6桁のHarmonized System(HS)に従います。履歴は、ソースが公表している場合、2010年1月から始まります。APIが扱うのは財のみです。

数値は、Narwhalが保有する国については報告国の税関または統計機関から、カバレッジ一覧にある181か国のうちそれ以外の国についてはUN Comtradeまたは他国の報告から取得します。すべての回答に、どのソースで作成されたかが示されます。どの国がどのソースで回答するかは、貿易の対象国ページに掲載しています。

回答するルートは7つで、すべて /v1/trade の下にあり、それぞれが同じパラメータ、同じ回答のMCPツールにもなっています。各リクエストでは、Narwhalのほかの部分と同様に、Authorization: Bearer ヘッダーでキーを渡します。

ルート

ルートMCPツール回答内容
GET /v1/trade/{country}/partnerstrade_get_partners1つの国のパートナー国別の輸出入。
GET /v1/trade/{country}/productstrade_get_products1つの国のHS品目別の輸出入(2桁、4桁、6桁)。
GET /v1/trade/{country}/products/{hs}trade_get_product1つの国の、1つのHSコードについての全パートナー国との貿易。
GET /v1/trade/flowstrade_get_flows複数の報告国、パートナー国、類にまたがるオープンクエリ。
GET /v1/trade/coveragetrade_get_coverage各国をどのソースが回答するか、保有する月。無料。
GET /v1/trade/hs-codestrade_list_hs_codes名前、レベル、親コードでHSコードを検索または一覧表示します。
GET /v1/trade/hs-codes/{code}trade_get_hs_code1つのHSコードと、その親コードおよび子コード。

各ルートには専用ページがあり、すべてのパラメータ、実際のレスポンス付きの動作するリクエスト、すべてのエラーを掲載しています。

ソース

各回答は1つのソースから返され、basis と source に示されます。basis のないリクエストでは、この順序で最初に行を保有するソースが使われます。ソースが1つの回答の中で混在することはなく、basis で名前を指定して1つを求められます。

basis出典内容到達
ownその国自身の税関または統計機関機関が公表したままの、機関独自の数値(自国通貨建て)。パートナー国。機関が提供する場合は、2桁、4桁、6桁の品目
third_partyUN Comtradeその国が国連に毎月提出する独自の申告。ソースを明記して提供します。パートナー国の合計のみ
partner_reported他国の税関報告他国がその国について報告した内容で、方向を入れ替えたもの。他国のその国からの輸入が、その国の輸出になります。別の測定方法であり、公式の数値ではありません。パートナー国。品目は2桁

他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_reported です。パートナー国報告の回答には公式の合計がなく、top、share、ytd、change は使えず、最大12か月までです。GET /v1/trade/coverage は、現在各国に回答するソースである answers_with を示します。

どの国がどのソースで回答するか: 貿易の対象国。

通貨

値は currency に示される通貨の整数単位で、小数の文字列です。デフォルトでは、ソースが公表している通貨です。currency=USD は、各月をその月の日次為替レートの平均で換算し、月ごとに使用したレートを fx に示し、換算したフィールドを calculated に挙げます。オープンクエリのルートでは、報告国ごとに公表通貨が異なるため、各行に通貨が示されます。

ページング

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

価格

貿易の呼び出しは1,000回あたり$2です。1行以上を返すリクエストは1回の呼び出しとなり、長い回答の各ページも1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料、カバレッジルートも無料です。クレジットとチャージについては料金表を参照してください。

エラー

エラーは、request_id を含む共通のエラー形式を使います。各ルートのページに、そのルートが返しうるエラーを掲載しています。以下がすべてです。

ステータスコード発生する場面
401, 402, 429unauthorized, insufficient_credits, rate_limitedキーがない、または無効な場合、残高が呼び出しの料金に満たない場合、あるいは1分あたりのリクエストが多すぎる場合。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 として拒否します。
404hs_code_not_foundそのHS版には、そのようなコードがありません。
404country_not_coveredNarwhalは、どのソースにもその国の貿易の行を保有していません。
404period_not_published指定した月が保有されていない場合(No trade rows for 2026-10.)、または ytd や change に必要な月が欠けている場合。
404basis_not_available求められたソース、または順序内のすべてのソースが、その問い合わせに該当するものを何も保有していない場合。detail に理由が示されます。例:その国自身の機関がパートナー国の合計のみで品目を提供していない場合や、パートナー国報告の回答が類(2桁)までしか届かない場合や、タイ自身の機関が4桁で保有しているのに6桁を求められた場合。カバレッジルートを参照してください。
404rate_not_availablecurrency=USD が求められ、ある月の為替レートがない場合。
503upstream_unavailable為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。
503trade_data_unavailable品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。

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

MCPツール

各ルートは、同じパラメータと同じ回答を持つ独立したMCPツールです。MCPツールは1回の結果で最大200行を返すため、cursor でページを送ってください。ツールは次のとおりです:

trade_list_hs_codestrade_get_hs_codetrade_get_coveragetrade_get_partnerstrade_get_productstrade_get_producttrade_get_flows

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