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

失業率履歴 API

1つの国について、現在受け入れられている失業率の時系列を取得します。

economics_get_unemployment_history を利用できるのは REST と、 economics_get_unemployment_history という MCP ツールです。どちらも同じデータ形式を返し、同じ月間クォータを消費します。

エンドポイントとリクエスト

REST エンドポイント
GET /v1/economics/{country}/unemployment/observations
リクエストの例
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/unemployment/observations?start=2026-07&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP で使用するツールは economics_get_unemployment_history です。以下の対応する引数を指定します。

パラメータ

この操作で受け付ける期間形式： YYYY, YYYY-MM, or YYYY-QN。

名前必須種別意味
countryはいパス · ISO alpha-3対応している国コードを大文字で1つ指定します。この操作のカバレッジ一覧を確認してください。
startいいえクエリ · YYYY、YYYY-MM、または YYYY-QN最初の観測期間。この期間を含みます。FreeとBasicでは、開始期間がプランの対象期間より前の場合、対象内の最初の期間に変更されます。その場合、レスポンスにはstartが含まれます。
endいいえクエリ · YYYY、YYYY-MM、または YYYY-QN最後の観測期間（その期間を含む）。
limitいいえクエリ · 整数、1～1000返す期間数の上限。デフォルトは 100 です。1ページの期間数がこれより少ない場合もあるため、next_cursor をたどってください。
cursorいいえクエリ · 不透明な文字列前のページの next_cursor。

レスポンス

レスポンスの例
{
  "country": "USA",
  "as_of": "2026-08-12T00:00:00Z",
  "observations": [
    {
      "period": "2026-07",
      "rate": "4.1"
    }
  ],
  "next_cursor": null
}
フィールド種別必須意味
country文字列はいリクエストした大文字の ISO alpha-3 国コード。観測値ごとではなく、ページごとに1回返します。
start文字列いいえプランの制約により、リクエストした start が後の期間に移動した場合にのみ含まれます。それより前の期間は返しません。
as_ofRFC 3339 タイムスタンプいいえこのページの最新の観測値をソースが最後に更新した時刻。UTC、秒単位です。
sourceオブジェクトいいえ配信事業者を通じて受け取った統計の出所情報。最新値を取得する操作を参照してください。
observations配列はい採用済みの観測値を古い順に、各期間につき1件返します。ソースにない値は省略し、補完しません。1ページの観測値の件数が limit より少ない場合もあるため、next_cursor が null になるまでたどってください。
observations[].period文字列はい観測値が表す公式の月または四半期。
observations[].rate小数文字列はい公表された率。単位はパーセントです。
next_cursor文字列または nullはい次のページを読むには、この値を変更せず cursor に渡してください。最終ページでは null です。

エラーとクォータ

  • 400 invalid_query — 国、期間、フィルター形式が無効です。
  • 400 invalid_cursor — カーソルの形式が不正か、別のフィルターまたは操作に対して発行されています。
  • 401 invalid_api_key — Bearer キーがないか拒否されました。
  • 403 plan_upgrade_required — 指定期間または範囲が、プランの履歴対象期間（Freeは12か月、Basicは5年）より前に終了します。
  • 404 series_not_found — リクエストに一致する承認済み観測値がありません。
  • 409 cursor_expired ページネーションのカーソルが古すぎるか、対象データが変更されています。カーソルなしで最初から取得してください。
  • 429 rate_limit_exceeded — ネットワークまたはアカウントの短時間枠の上限に達しました。再試行は、次のヘッダーの指定に従って待機してから行ってください： Retry-After。
  • 429 quota_exhausted — アカウントが月間枠に達しました。
  • 503 economics_unavailable — Narwhal は受け入れ済み公開データを安全に提供できません。

クォータを消費するのは成功したデータレスポンスだけです。次を参照： すべてのエラー、ヘッダー、再試行規則。

鮮度

このルートは、次の時点で Narwhal が受け入れた現在の系列を返します： as_of。これは現行版の履歴であり、過去の公開版をすべて再構成したものではありません。

公式ソースは観測値が疎で、公開する履歴の深さも異なる場合があります。Narwhal は補間や値の繰り越しをせず、欠損した観測値を省略します。

読む ソース確認、検証、保存済みリリース、確認失敗の仕組み。

現在の公開ベータ版カバレッジ

34 国

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, PHL, POL, PRT, SAU, SGP, SVN, SWE, USA

利用可能な公式履歴は、この操作の国別カバレッジに従います。最初に利用できる期間はソースによって異なります。

インドネシアと地域別の 経済データ ルートは公開されていません。日次 FX データの提供先は 為替API。

戻る： すべての 経済データ 操作。