ドキュメント
APIリファレンスサイト
すべてのドキュメントを閲覧

経済データAPIリファレンス

国と指標ごとのカバレッジを示した最新リリースと過去の観測値です。

7つのルートが最新の採用済み公式リリースを返します。対応する7つの /observations ルートは現在受け入れられている時系列を返します。REST と MCP は同じスキーマを使用し、同じ月間クォータを消費します。

ベースURLとパラメータ

REST ベースパス
https://api.narwhalapi.com/v1/economics/{country}
  • country には、対応している大文字の ISO alpha-3 コードを指定します。
  • period は任意です。最新リリースを取得する場合は省略し、期間を指定する場合は操作に対応する月、四半期、年の形式を使用します。
  • /v1/economics/{country}/cpi などのコア経済データエンドポイントと対応する MCP ツールは、主要指標の暫定的な初回推計値を返す場合があり、レスポンスには暫定値であることが明示されず、ソースが確定値を公表すると Narwhal API がこれらの値を置き換えます。
  • すべてのリクエストには、次で説明する Bearer ヘッダーが必要です： 認証。
既知の期間を1つリクエスト
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/cpi?period=2026-07" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

国

36 国

AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA

カバレッジは操作と国によって異なります。各操作に対応国が記載されています。

最新リリース

操作ページを開くと、正確なパラメータ、受け付ける期間形式、レスポンスフィールド、例、エラー、鮮度、現在の上限を確認できます。

操作REST パス期間
消費者物価指数/v1/economics/{country}/cpiYYYY-MM
インフレ率/v1/economics/{country}/inflationYYYY-MM
失業率/v1/economics/{country}/unemploymentYYYY, YYYY-MM, or YYYY-QN
労働力率/v1/economics/{country}/labour-force-participationYYYY, YYYY-MM, or YYYY-QN
国内総生産/v1/economics/{country}/gdpYYYY-QN
GDP 成長率/v1/economics/{country}/gdp-growthYYYY-QN
財貿易/v1/economics/{country}/tradeYYYY or YYYY-MM

過去の観測値

過去データのルートで受け付けるのは start, end, limit、および cursor。結果は古い順で、過去の公開版すべてではなく、現在受け入れられている系列を示します。

操作REST パス期間
消費者物価指数の履歴/v1/economics/{country}/cpi/observationsYYYY-MM
インフレ率の履歴/v1/economics/{country}/inflation/observationsYYYY-MM
失業率の履歴/v1/economics/{country}/unemployment/observationsYYYY, YYYY-MM, or YYYY-QN
労働力率の履歴/v1/economics/{country}/labour-force-participation/observationsYYYY, YYYY-MM, or YYYY-QN
国内総生産の履歴/v1/economics/{country}/gdp/observationsYYYY-QN
GDP 成長率の履歴/v1/economics/{country}/gdp-growth/observationsYYYY-QN
財貿易の履歴/v1/economics/{country}/trade/observationsYYYY-MM

フィールド規則

フィールドまたは規則意味
country指定された ISO alpha-3 国コード。
periodレスポンスが表す正確な公式の月、四半期、または年。
released_onNarwhal の取得時刻ではなく、公式の公表日。
小数文字列経済数値は正確な10進表現を保つため文字列です。
単位と基準パーセントを表すフィールドには、そのことがわかる名前を付けています。通貨と指数の基準も明示します。フラグは、系列が季節調整されていない場合、または年率換算されている場合にのみ表示されます。
欠落したリリースNarwhalは捏造、繰り越し、欠落値のゼロ変換をせず、失敗として処理します。

IDで系列の履歴を取得

GET /v1/economics/series/{series_id}/observationsは、IDで指定した1つの系列の履歴を返します。MCPツール：economics_read_series_observations。IDはUUIDです。経済発表カレンダーのseries_idで使われるusa-new-home-salesなどのスラッグは受け付けず、400 invalid_queryを返します。オーストラリアの月次CPI指標（例：284aaefe-7919-4728-bc15-50879ba77211）とニュージーランドの四半期CPIの2系列を提供します。

省略可能なstartとendは、YYYY、YYYY-MM、YYYY-MM-DD、YYYY-QNを受け付けます。limitは1–1000（デフォルト100）です。次のページを取得するにはnext_cursorをcursorとして渡します。FreeとBasicではプランの履歴対象期間だけを取得できます。それより前の範囲は403 plan_upgrade_requiredを返します。未知の系列は404 not_foundを返します。

レスポンスの例
{
  "country": "AUS",
  "series_id": "284aaefe-7919-4728-bc15-50879ba77211",
  "unit": "percent",
  "observations": [
    {
      "period": "2018-09",
      "value": "2",
      "released_on": "2025-10-29"
    },
    {
      "period": "2018-10",
      "value": "2.3",
      "released_on": "2025-10-29"
    }
  ],
  "next_cursor": null
}

country、series_id、unit、observations、next_cursorは常に含まれます。最終ページのnext_cursorはnullです。各観測値にはperiod、value、released_onがあります。currencyとsourceは該当する場合だけ含まれます。

OpenAPI と API の検出

現在の公開ベータ版の制限

米国、英国、ドイツ、日本、カナダの国債利回り曲線。RESTとMCPで、公表元の特定日データやページ分割された履歴を取得できます。

インドネシアと地域別のルートは、Economics APIの公開ベータ版には含まれません。

参照： エラーとクォータ で、系列が存在しない場合やサービスを利用できない場合の動作を確認してください。