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

オープンクエリ貿易APIリファレンス

任意の報告国、パートナー国、HSの類を1回の呼び出しで問い合わせます。例:ある品目の上位輸出国や、ある国と別の国の比較。

概要

GET /v1/trade/flows

GET /v1/trade/flows は、指定した任意の報告国、パートナー国、HSの類の輸出入を、1回の呼び出しで返します。reporter、partner、hs はそれぞれ、最大10件のカンマ区切りの一覧を受け付けます。1行は、1つの報告国、月、方向、パートナー国、類です。

国や品目をまたぐ質問に使います。ある類を誰が輸出しているか、ある国が別の国とどう貿易しているか、2つの国の並べての比較などです。reporter、partner、hs の少なくとも1つを指定してください。reporter を省略すると、Narwhalが自国の機関またはUN Comtradeから直接保有しているすべての国を意味します。

各行には、報告国によって回答するソースが異なりうるため、それぞれの basis、source、currency が示されます。異なるソースの行が合算されることはありません。期間は最大12か月で、start と end がない場合は、各報告国が最新の月で回答します。hs がない場合、行はパートナー国の合計で、hs がある場合は類の行です。MCPツールは trade_get_flows で、同じパラメータを受け付けます。

リクエスト

2026年6月の英国とドイツの類85(電気機械)の輸出、最初のページ(5行):

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
類85の輸出、英国とドイツ
{
  "scope": "goods",
  "bases": [
    "own"
  ],
  "reporters": [
    "DEU"
  ],
  "latest_period": "2026-06",
  "note": null,
  "fx": null,
  "calculated": [],
  "total": 396,
  "rows": [
    {
      "reporter": "DEU",
      "basis": "own",
      "source": "Eurostat Comext",
      "currency": "EUR",
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "ABW",
      "partner_label": "Aruba",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "108666",
      "net_weight_kg": "731"
    },
    {
      "reporter": "DEU",
      "basis": "own",
      "source": "Eurostat Comext",
      "currency": "EUR",
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "AFG",
      "partner_label": "Afghanistan",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "153236",
      "net_weight_kg": "2893"
    }
  ],
  "next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}

ページには5行のうち最初の2行を示しています。total は396なので、さらにページが続きます。1ページ目にはドイツの行だけが入っており、reporters はそのページの報告国を挙げるため、2つを求めても DEU だけが示されます。

パラメータ

パラメータ場所種別必須デフォルト許容値と意味
reporterクエリ文字列いいえ直接保有するすべての国報告国。ISO 3166-1 alpha-3コード(大文字)で、最大10件のカンマ区切りの一覧。例:GBR,DEU。国ではないコードには400が返り、そのコードが示されます。カバレッジ一覧にない国には404 country_not_covered が返ります。自国のソースが保有されていない報告国は、他国の報告から回答され、名前で指定する必要があります。
partnerクエリ文字列いいえすべてのパートナー国パートナー国。ISO 3166-1 alpha-3コード(大文字)で、最大10件のカンマ区切りの一覧。
hsクエリ文字列いいえなしHSの類。2桁で、最大10件のカンマ区切りの一覧。例:85,87。その場合、行は類の行です。省略すると、行はパートナー国の合計です。オープンクエリで保有しているのは類のみです。
flowクエリ文字列いいえ両方向export または import。
startクエリ文字列、YYYY-MMいいえ各報告国の最新の月最初の月(含む)。start から end までは最大12か月です。
endクエリ文字列、YYYY-MMいいえ各報告国の最新の月最後の月(含む)。start と end の片方のみの場合は、その月のみ。
basisクエリ文字列いいえ各報告国が保有する最良のソースown、third_party、partner_reported。このソースのみが回答します。問い合わせに該当する行がないソースには、404 basis_not_available が返ります。
currencyクエリ文字列いいえ各報告国自身の通貨(各行に表示)USD。各行をその月の日次レートの平均で換算します。
include_groupsクエリブール値いいえfalsetrue を指定すると、EUやASEANなど、公表元が表示するグループ行も返します。グループ行は、合計、順位、構成比には含まれません。
limitクエリ整数いいえ5001〜1000。1ページの最大行数。
cursorクエリ文字列いいえなし前のページの next_cursor。他のパラメータは変更しません。

レスポンス

回答には次のフィールドがあります。

フィールド意味
scopegoods。
basesこの回答の行の出典となるソース。それぞれ own、third_party、partner_reported。
reportersこのページに行がある報告国を、並べ替えて示します。後のページではさらに挙がることがあります。
latest_period直接保有している行の中で最新の月。ない場合は null。
note数値を使う前にお読みください。行がパートナー国報告の場合に設定され、それ以外は null です。
fxcurrency=USD の場合:各月に使われたレート。period、from_currency、to_currency、rate、days を含みます。それ以外は null。
calculatedNarwhalが算出したフィールドの名前。
total全ページにわたる、一致する行数。
next_cursor次のページのカーソル。最後のページでは null。

rows の各項目は、1つの報告国、月、方向、パートナー国、類です。

フィールド意味
reporter報告国のISO 3166-1 alpha-3コード。
basisこの行のソース:own、third_party、partner_reported。
sourceこの行の公表元。
currencyこの行の値のISO 4217コード。
flowexport または import。
period月(YYYY-MM)。
period_typemonth。
period_start, period_endその行が対象とする最初の日と最後の日(YYYY-MM-DD)。
partner, partner_label, partner_kind, unallocated_reasonパートナー国ルートと同じです。
product_codehs が送られた場合は類。パートナー国の合計では null。
valuecurrency の整数単位。小数の文字列です。
net_weight_kg公表元が提供している場合の、キログラム単位の正味重量。それ以外は null。

その他の例

パートナー国の合計のみの報告国は除外されます

類85における米国の中国からの輸入。カナダとメキシコも指定。両国の機関はパートナー国の合計のみを提供するため、回答するのは米国だけです:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"
中国からの類85の輸入
{
  "scope": "goods",
  "bases": [
    "own"
  ],
  "reporters": [
    "USA"
  ],
  "latest_period": "2026-06",
  "note": null,
  "fx": null,
  "calculated": [],
  "total": 1,
  "rows": [
    {
      "reporter": "USA",
      "basis": "own",
      "source": "US Census Bureau",
      "currency": "USD",
      "flow": "import",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "5834371932",
      "net_weight_kg": null
    }
  ],
  "next_cursor": null
}

パートナー国の合計のみの報告国

指名したすべての報告国がパートナー国の合計のみを提供し、hs が送られた場合、呼び出しには404が返り、無料です:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"
カナダ、類85
{
  "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. See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}

ソース

各報告国は、保有されている最良のソースから回答します。自国の機関、次にUN Comtradeへの申告(パートナー国の合計のみ)の順で、どちらも保有されていない報告国は、他国の報告から回答され、partner_reported と表示されます。類別では、UN Comtradeは何も保有していません。basis は、すべての報告国に1つのソースを強制します。自国の機関がパートナー国の合計のみを提供する報告国には類の行がなく、他の報告国が回答する場合は除外され、どの報告国も回答できない場合は404 basis_not_available が返ります。

通貨

各行は、その報告国自身の通貨で、行の currency に示されます。currency=USD は、すべての行をその月の日次レートの平均で換算し、そのレートを fx に挙げます。レートのない月には404 rate_not_available が返り、為替レートのソースが利用できない場合は503 upstream_unavailable が返ります。

ページング

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_queryreporter、partner、hs のいずれも指定されていない場合(an open query with none is the whole store)、end が start より前の場合、期間が12か月を超える場合、一覧が10件を超える場合、報告国が国ではない場合、パラメータが許容値の範囲外の場合、または as_of や version が送られた場合。パートナー国報告の回答が、30を超える報告国・パートナー国・類の組み合わせを必要とする場合も同様です。
400invalid_cursorカーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。
400range_too_large回答が200,000行を超える場合、またはパートナー国のない類の行が36報告国・月を超える場合。報告国、パートナー国、類をより少なく、または期間をより短く指定してください。
404country_not_covered指名した報告国がカバレッジ一覧にない場合(ATA is not in the trade coverage list.)。
404basis_not_availablebasis が、問い合わせに該当する行のないソースを指定している場合、または指名したすべての報告国がパートナー国の合計のみを保有し、hs が送られた場合。
404rate_not_availablecurrency=USD が求められ、ある月の為替レートがない場合。
503upstream_unavailable為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。
503trade_data_unavailable品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。

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

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