オープンクエリ貿易APIリファレンス
任意の報告国、パートナー国、HSの類を1回の呼び出しで問い合わせます。例:ある品目の上位輸出国や、ある国と別の国の比較。
概要
GET /
GET / は、指定した任意の報告国、パートナー国、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_ で、同じパラメータを受け付けます。
リクエスト
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"{
"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_ が返ります。自国のソースが保有されていない報告国は、他国の報告から回答され、名前で指定する必要があります。 |
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_、partner_。このソースのみが回答します。問い合わせに該当する行がないソースには、404 basis_ が返ります。 |
currency | クエリ | 文字列 | いいえ | 各報告国自身の通貨(各行に表示) | USD。各行をその月の日次レートの平均で換算します。 |
include_ | クエリ | ブール値 | いいえ | false | true を指定すると、EUやASEANなど、公表元が表示するグループ行も返します。グループ行は、合計、順位、構成比には含まれません。 |
limit | クエリ | 整数 | いいえ | 500 | 1〜1000。1ページの最大行数。 |
cursor | クエリ | 文字列 | いいえ | なし | 前のページの next_。他のパラメータは変更しません。 |
レスポンス
回答には次のフィールドがあります。
| フィールド | 意味 |
|---|---|
scope | goods。 |
bases | この回答の行の出典となるソース。それぞれ own、third_、partner_。 |
reporters | このページに行がある報告国を、並べ替えて示します。後のページではさらに挙がることがあります。 |
latest_ | 直接保有している行の中で最新の月。ない場合は null。 |
note | 数値を使う前にお読みください。行がパートナー国報告の場合に設定され、それ以外は null です。 |
fx | currency=USD の場合:各月に使われたレート。period、from_、to_、rate、days を含みます。それ以外は null。 |
calculated | Narwhalが算出したフィールドの名前。 |
total | 全ページにわたる、一致する行数。 |
next_ | 次のページのカーソル。最後のページでは null。 |
rows の各項目は、1つの報告国、月、方向、パートナー国、類です。
| フィールド | 意味 |
|---|---|
reporter | 報告国のISO 3166-1 alpha-3コード。 |
basis | この行のソース:own、third_、partner_。 |
source | この行の公表元。 |
currency | この行の値のISO 4217コード。 |
flow | export または import。 |
period | 月(YYYY-MM)。 |
period_ | month。 |
period_ | その行が対象とする最初の日と最後の日(YYYY-MM-DD)。 |
partner, partner_ | パートナー国ルートと同じです。 |
product_ | hs が送られた場合は類。パートナー国の合計では null。 |
value | currency の整数単位。小数の文字列です。 |
net_ | 公表元が提供している場合の、キログラム単位の正味重量。それ以外は 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"{
"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"{
"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_ と表示されます。類別では、UN Comtradeは何も保有していません。basis は、すべての報告国に1つのソースを強制します。自国の機関がパートナー国の合計のみを提供する報告国には類の行がなく、他の報告国が回答する場合は除外され、どの報告国も回答できない場合は404 basis_ が返ります。
通貨
各行は、その報告国自身の通貨で、行の currency に示されます。currency=USD は、すべての行をその月の日次レートの平均で換算し、そのレートを fx に挙げます。レートのない月には404 rate_ が返り、為替レートのソースが利用できない場合は503 upstream_ が返ります。
ページング
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 | reporter、partner、hs のいずれも指定されていない場合(an open query with none is the whole store)、end が start より前の場合、期間が12か月を超える場合、一覧が10件を超える場合、報告国が国ではない場合、パラメータが許容値の範囲外の場合、または as_ や version が送られた場合。パートナー国報告の回答が、30を超える報告国・パートナー国・類の組み合わせを必要とする場合も同様です。 |
400 | invalid_cursor | カーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。 |
400 | range_too_large | 回答が200,000行を超える場合、またはパートナー国のない類の行が36報告国・月を超える場合。報告国、パートナー国、類をより少なく、または期間をより短く指定してください。 |
404 | country_not_covered | 指名した報告国がカバレッジ一覧にない場合(ATA is not in the trade coverage list.)。 |
404 | basis_not_available | basis が、問い合わせに該当する行のないソースを指定している場合、または指名したすべての報告国がパートナー国の合計のみを保有し、hs が送られた場合。 |
404 | rate_not_available | currency=USD が求められ、ある月の為替レートがない場合。 |
503 | upstream_unavailable | 為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。 |
503 | trade_data_unavailable | 品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。 |
このページは役に立ちましたか?