貿易データAPIリファレンス
Narwhalが保有する国については当該国の税関または統計機関から、それ以外の国についてはUN Comtradeまたは他国の報告から、パートナー国別・HS品目別の財貿易を月ごとに読み取ります。
概要
貿易データAPIは、パートナー国別・品目別の財貿易を1か月単位で返します。1行は、ある月における1つの方向(輸出または輸入)について、パートナー国または品目と、通貨の整数単位による値を示します。品目は2桁、4桁、6桁のHarmonized System(HS)に従います。履歴は、ソースが公表している場合、2010年1月から始まります。APIが扱うのは財のみです。
数値は、Narwhalが保有する国については報告国の税関または統計機関から、カバレッジ一覧にある181か国のうちそれ以外の国についてはUN Comtradeまたは他国の報告から取得します。すべての回答に、どのソースで作成されたかが示されます。どの国がどのソースで回答するかは、貿易の対象国ページに掲載しています。
回答するルートは7つで、すべて / の下にあり、それぞれが同じパラメータ、同じ回答のMCPツールにもなっています。各リクエストでは、Narwhalのほかの部分と同様に、Authorization: Bearer ヘッダーでキーを渡します。
ルート
| ルート | MCPツール | 回答内容 |
|---|---|---|
GET / | trade_ | 1つの国のパートナー国別の輸出入。 |
GET / | trade_ | 1つの国のHS品目別の輸出入(2桁、4桁、6桁)。 |
GET / | trade_ | 1つの国の、1つのHSコードについての全パートナー国との貿易。 |
GET / | trade_ | 複数の報告国、パートナー国、類にまたがるオープンクエリ。 |
GET / | trade_ | 各国をどのソースが回答するか、保有する月。無料。 |
GET / | trade_ | 名前、レベル、親コードでHSコードを検索または一覧表示します。 |
GET / | trade_ | 1つのHSコードと、その親コードおよび子コード。 |
各ルートには専用ページがあり、すべてのパラメータ、実際のレスポンス付きの動作するリクエスト、すべてのエラーを掲載しています。
ソース
各回答は1つのソースから返され、basis と source に示されます。basis のないリクエストでは、この順序で最初に行を保有するソースが使われます。ソースが1つの回答の中で混在することはなく、basis で名前を指定して1つを求められます。
basis | 出典 | 内容 | 到達 |
|---|---|---|---|
own | その国自身の税関または統計機関 | 機関が公表したままの、機関独自の数値(自国通貨建て)。 | パートナー国。機関が提供する場合は、2桁、4桁、6桁の品目 |
third_ | UN Comtrade | その国が国連に毎月提出する独自の申告。ソースを明記して提供します。 | パートナー国の合計のみ |
partner_ | 他国の税関報告 | 他国がその国について報告した内容で、方向を入れ替えたもの。他国のその国からの輸入が、その国の輸出になります。別の測定方法であり、公式の数値ではありません。 | パートナー国。品目は2桁 |
他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_ です。パートナー国報告の回答には公式の合計がなく、top、share、ytd、change は使えず、最大12か月までです。GET / は、現在各国に回答するソースである answers_ を示します。
どの国がどのソースで回答するか: 貿易の対象国。
通貨
値は currency に示される通貨の整数単位で、小数の文字列です。デフォルトでは、ソースが公表している通貨です。currency=USD は、各月をその月の日次為替レートの平均で換算し、月ごとに使用したレートを fx に示し、換算したフィールドを calculated に挙げます。オープンクエリのルートでは、報告国ごとに公表通貨が異なるため、各行に通貨が示されます。
ページング
limit は1ページの最大行数を1〜1000で指定します。パートナー国、品目、1品目、オープンクエリの各ルートではデフォルトが500、GET / では100です。さらに行が一致する場合、next_ に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_ が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。
価格
貿易の呼び出しは1,000回あたり$2です。1行以上を返すリクエストは1回の呼び出しとなり、長い回答の各ページも1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料、カバレッジルートも無料です。クレジットとチャージについては料金表を参照してください。
エラー
エラーは、request_ を含む共通のエラー形式を使います。各ルートのページに、そのルートが返しうるエラーを掲載しています。以下がすべてです。
| ステータス | コード | 発生する場面 |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | キーがない、または無効な場合、残高が呼び出しの料金に満たない場合、あるいは1分あたりのリクエストが多すぎる場合。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 | hs_code_not_found | そのHS版には、そのようなコードがありません。 |
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 | rate_not_available | currency=USD が求められ、ある月の為替レートがない場合。 |
503 | upstream_unavailable | 為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。 |
503 | trade_data_unavailable | 品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。 |
MCPツール
各ルートは、同じパラメータと同じ回答を持つ独立したMCPツールです。MCPツールは1回の結果で最大200行を返すため、cursor でページを送ってください。ツールは次のとおりです:
trade_ list_ hs_ codestrade_ get_ hs_ codetrade_ get_ coveragetrade_ get_ partnerstrade_ get_ productstrade_ get_ producttrade_ get_ flowsこのページは役に立ちましたか?