パートナー国別貿易APIリファレンス
1つの国の輸出入をパートナー国別に読み取ります。パートナー国、月、方向ごとに1行で、行の合計の横に公表元自身の合計を併記します。
概要
GET /
GET / は、1つの国の財貿易をパートナー国別に返します。パートナー国、月、方向ごとに1行です。start と end がない場合、回答は保有する最新の月です。
誰とどれだけ貿易しているかを調べるために使います。同じ国を品目別に見るには品目ルートを、1つの品目を全パートナー国と対比するには1品目ルートを使います。複数の国を1回の呼び出しで比較するには、オープンクエリのルートを使います。
すべての回答は、作成したソースを basis と source に示し、行の合計の横に公表元自身の合計を totals に含めます。hs を指定した場合、totals はその品目のものとなり、official_ は null です。MCPツールは trade_ で、同じパラメータを受け付けます。
リクエスト
2026年6月の英国の輸出相手上位3か国と、実際のレスポンス:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"{
"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": "37649508686",
"sum_of_rows": "37649508686"
}
],
"fx": null,
"calculated": [
"sum_of_rows",
"rank"
],
"total": 3,
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "5316654916",
"net_weight_kg": "76287894",
"rank": 1,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "4735227787",
"net_weight_kg": "341314142",
"rank": 2,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}ページには3行のうち最初の2行を示しています。basis が own のため、英国歳入関税庁(HM Revenue & Customs)が回答し、official_ は sum_ と等しくなっています。top を送ったため rank が設定され、calculated に挙がっています。
パラメータ
| パラメータ | 場所 | 種別 | 必須 | デフォルト | 許容値と意味 |
|---|---|---|---|---|---|
country | パス | 文字列 | はい | なし | 報告国のISO 3166-1 alpha-3コード(大文字)。例:GBR。国ではないコードには400が返ります。数値のない国には404 country_ が返ります。 |
partner | クエリ | 文字列 | いいえ | すべてのパートナー国 | 1つのパートナー国のISO 3166-1 alpha-3コード(大文字)。その国のパートナー国ではないコードには、400 unknown_ が返ります。 |
flow | クエリ | 文字列 | いいえ | 両方向 | export または import。 |
start | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最初の月(含む)。start のみで end がない場合、回答は保有する最新の月までです。start が end より後の場合は400が返ります。 |
end | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最後の月(含む)。end のみの場合、回答はそれ以前で保有する最新の月です。 |
hs | クエリ | 文字列 | いいえ | すべての品目 | この品目の貿易のみ。2桁、4桁、6桁のコード(85、8517、851713)で指定し、各パートナー国の構成比を返します。他の桁数のコードには400が返ります。タイは4桁で保有しているため、タイに6桁のコードを指定すると404 basis_ が返ります。 |
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_。他のパラメータは変更しません。 |
レスポンス
回答には次のフィールドがあります。すべての行で同じものは、ここに1回だけ載せています。
| フィールド | 意味 |
|---|---|
country | 回答の対象である報告国のISO 3166-1 alpha-3コード。 |
basis | 回答したソース:own、third_(UN Comtrade)、partner_。 |
source | 公表元。例:HM Revenue & Customs、Eurostat Comext、UN Comtrade、Customs reports of other countries。 |
reporters_ | partner_ の場合:回答に入れ替えて反映された報告の報告国の count と countries。他のソースでは null。 |
note | 数値を使う前にお読みください。パートナー国報告の回答に設定され、それ以外は null です。 |
coverage | full または partial。パートナー国報告の回答は partial です。 |
partner_ | すべてのパートナー国が掲載される場合は all、公表元が上位のパートナー国と残りの1行のみを表示する場合は top_。パートナー国報告の回答では null。 |
scope | goods。 |
currency | 回答内のすべての値のISO 4217コード。 |
classification | HS(Harmonized System)。 |
edition | 指定したすべての月を1つの版が対象とする場合のHS版(2007、2012、2017、2022)。月によって異なる場合は null で、各行にそれぞれの版が示されます。 |
edition_ | 公表元が版を示している場合は as_、Narwhalが年から割り出した場合は inferred_。 |
valuation_ | 公表元が貿易をどのように評価しているか。例:輸出はFOB、輸入はCIF。示されていない場合は not_。 |
trade_ | 公表元が示している場合は general または special。それ以外は not_。 |
partner_ | パートナー国が、公表元が示すとおりに、原産地、積出地、仕向地のどれで数えられているか。示されていない場合は not_。 |
trade_ | 数値が何を対象としているか。例:all_、extra_、intra_。 |
latest_ | Narwhalがこの国とソースについて保有する最新の月。 |
total_ | official_ の基準:customs、balance_、eurostat_。公表元が合計を示していない場合は null。 |
totals | 月と方向ごとに1項目:period、flow、official_(公表元自身の財の合計。存在しない場合は null)、sum_(その月と方向について、グループ行を除くすべてのパートナー国の行の合計。算出値)。hs がない場合は、partner が行を絞り込む場合も含め、その月の財の合計全体を保持します。hs がある場合(および1品目ルートでは)、代わりにその品目の合計を保持します。sum_ は、回答の全ページの行の合計(partner が指定されていればその国の行。top とページングでは減りません)で、公表元は1つの品目の合計を表示しないため、official_ は null です。 |
fx | currency=USD の場合、および複数の通貨にまたがるパートナー国報告の回答の場合:各月に使われたレート。period、from_、to_、rate、平均に使った days を含みます。それ以外は null。 |
calculated | Narwhalが算出したフィールドの名前。例:sum_、rank、share、value、official_。 |
total | 全ページにわたる、一致する行数。 |
next_ | 次のページのカーソル。最後のページでは null。 |
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。 |
その他の例
1つのパートナー国との両方向
ドイツと中国、2026年1月から6月、両方向:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"{
"country": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "EUR",
"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": "eurostat_concept",
"totals": [
{
"period": "2026-01",
"flow": "export",
"official_total": "121792305000",
"sum_of_rows": "121792305000"
},
{
"period": "2026-01",
"flow": "import",
"official_total": "106754947046",
"sum_of_rows": "106754947046"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 12,
"rows": [
{
"flow": "export",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "5559611667",
"net_weight_kg": "355538457",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "import",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "8853410701",
"net_weight_kg": "1020758294",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}ページには12行のうち最初の2行と、12件の totals 項目のうち最初の2件を示しています。ドイツはEurostat Comextからユーロで回答されます。
その国自身の機関が提供しない品目
カナダ自身の機関はパートナー国の合計のみを提供します。1つの品目を求めるリクエストには404が返り、無料です:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"{
"type": "https://narwhalapi.com/problems/basis-not-available",
"title": "Basis not available",
"status": 404,
"detail": "Narwhal holds CAN's own partner totals only, not its products; UN Comtrade is held as partner totals only, not by product; partner-reported answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}ソース
各リクエストには1つのソースが回答します。この順序で、行を保有する最初のソースです。その国自身の税関または統計機関(basis は own)、その国自身のUN Comtradeへの申告(third_、パートナー国の合計のみ)、次に、その国について他国が報告した内容で方向を入れ替えたもの(partner_)。他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_ で、partner_ は類(2桁)までしか届きません。basis はソースを名前で1つ求めます。回答の basis、source、note フィールドが、どのソースが回答したかを示し、ソースが1つの回答の中で混在することはありません。パートナー国報告の回答は、その国自身の数値とは別の測定であり、公式の数値ではありません。ソースのパートナー国一覧は短いことがあります。partner_ が top_ の場合、公表元は上位のパートナー国と残りの1行のみを示し、行を合計すると全体と一致します。
通貨
値は 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 | rate_not_available | currency=USD が求められ、ある月の為替レートがない場合。 |
503 | upstream_unavailable | 為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。 |
503 | trade_data_unavailable | 品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。 |
このページは役に立ちましたか?