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

人口履歴API

世界銀行の、1つの国の年次総人口を取得します。

economics_get_population_history を利用できるのは REST と、 economics_get_population_history MCPツール。どちらも同じデータ形式を返し、同じクレジットを使用します。

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

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

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

パラメータ

この操作で受け付ける期間形式: YYYY。

名前必須種別意味
countryはいパス · ISO alpha-3対応している国コードを大文字で1つ指定します。この操作のカバレッジ一覧を確認してください。
startいいえクエリ · YYYY最初の観測期間(その期間を含む)。
endいいえクエリ · YYYY最後の観測期間(その期間を含む)。
limitいいえクエリ · 整数、1~1000返す期間数の上限。デフォルトは 100 です。1ページの期間数がこれより少ない場合もあるため、next_cursor をたどってください。
cursorいいえクエリ · 不透明な文字列前のページの next_cursor。
versionいいえクエリ · first_reported`first_reported`のみ指定できます。各期間の初回保存値を`first_reported_at`とともに返します。`as_of`とは併用できません。
as_ofいいえクエリ · YYYY-MM-DD指定したUTC日の終了時点までに公表されていた系列を返します。`version`とは併用できません。

レスポンス

レスポンスの例
{
  "country": "USA",
  "as_of": "2026-10-08T00:00:00Z",
  "source": {
    "publisher": "UN Population Division (World Population Prospects), national statistical offices, Eurostat, U.S. Census Bureau, Pacific Community: mid-year estimates",
    "distributor": "World Bank, World Development Indicators (CC BY 4.0)"
  },
  "unit": "person",
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "value": "340003797"
    },
    {
      "period": "2025",
      "value": "341784857"
    }
  ],
  "next_cursor": null
}
フィールド種別必須意味
country文字列はいリクエストした大文字の ISO alpha-3 国コード。観測値ごとではなく、ページごとに1回返します。
as_ofRFC 3339 タイムスタンプいいえこのページの最新の観測値をソースが最後に更新した時刻。UTC、秒単位です。
sourceオブジェクトはいpublisherに元の公表機関を、distributorに世界銀行の世界開発指標(CC BY 4.0)を示します。
unit文字列はい常にpersonです。
frequency文字列はい常にannualです。
observations配列はい採用済みの観測値を古い順に、各期間につき1件返します。ソースにない値は省略し、補完しません。1ページの観測値の件数が limit より少ない場合もあるため、next_cursor が null になるまでたどってください。
observations[].period文字列はい観測値が表す公式の月、四半期、または年。
observations[].first_reported_atRFC 3339 タイムスタンプいいえこのUTCタイムスタンプはversion=first_reportedを指定した場合にのみ含まれ、Narwhalがその期間のデータを初めて保存した時刻を示します。各測定値が別々に保存された場合は、そのうち最も遅い時刻を示します。取得開始前に公表された期間には、Narwhalによる初回取得時刻が表示されます。
observations[].value小数文字列はい年央の人口で、単位は人(整数)です。法的地位や国籍にかかわらず、すべての居住者を数えます。最新の年は推計値の場合があります。
next_cursor文字列または nullはい次のページを読むには、この値を変更せず cursor に渡してください。最終ページでは null です。

APIエラーとクレジット

  • 400 invalid_query — 国、期間、フィルターの形式が無効であるか、as_ofとversionが同時に送信されています。
  • 400 invalid_cursor — カーソルの形式が不正か、別のフィルターまたは操作に対して発行されています。
  • 401 invalid_api_key — Bearer キーがないか拒否されました。
  • 404 series_not_found — リクエストに一致する承認済み観測値がありません。
  • 409 cursor_expired ページネーションのカーソルが古すぎるか、対象データが変更されています。カーソルなしで最初から取得してください。
  • 429 rate_limit_exceeded — ネットワークまたはアカウントの短時間枠の上限に達しました。再試行は、次のヘッダーの指定に従って待機してから行ってください: Retry-After。
  • 402 insufficient_credits 残高では呼び出しの料金を支払えない場合です。
  • 503 economics_unavailable — Narwhal は受け入れ済み公開データを安全に提供できません。

Only a successful data response costs credit. 参照: すべてのエラー、ヘッダー、再試行規則。

鮮度

このルートはデフォルトで、Narwhalが現在採用している系列を返します。レスポンスのas_ofは、最新の観測値の更新時刻です。どのキーでも、as_ofまたはversion=first_reportedで過去の公表時点のデータを取得できます。この履歴はNarwhalによる初回取得時点から始まり、過去のすべての公表内容を再構成したものではありません。

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

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

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

215 国

ABW, AFG, AGO, ALB, AND, ARE, ARG, ARM, ASM, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, CHE, CHL, CHN, CIV, CMR, COD, COG, COL, COM, CPV, CRI, CUB, CUW, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESP, EST, ETH, FIN, FJI, FRA, FRO, FSM, GAB, GBR, GEO, GHA, GIB, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HRV, HTI, HUN, IDN, IMN, IND, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, MYS, NAM, NCL, NER, NGA, NIC, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, USA, UZB, VCT, VEN, VGB, VIR, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE

年次の履歴は1960年から始まり、パレスチナは1990年からです。コソボとチャンネル諸島にはISO alpha-3コードがないため、対象外です。最新値の人口ルートはありません。成功したリクエストは、経済データの1回分として課金されます。

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

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

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