瀏覽全部文件

人口歷史資料 API 參考

從世界銀行取得單一國家的年度總人口。

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一個受支援的大寫國家代碼;請參閱此操作的涵蓋清單。
start否查詢·YYYY起始觀測期間(含該期間)。
end否查詢·YYYY結束觀測期間(含該期間)。
limit否查詢·整數,1–1000傳回的期間數上限。預設值為 100。頁面可能包含較少的期間;請繼續使用 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 國家代碼。每頁傳回一次,不在每筆觀測資料中重複。
as_ofRFC 3339 時間戳記否來源最後更新本頁最新觀測值的時間,精確到整秒,使用 UTC。
source對象是publisher 列出原始發布機構,distributor 為世界銀行世界發展指標(CC BY 4.0)。
unit字串是固定為 person。
frequency字串是固定為 annual。
observations陣列是按時間由早到晚排列的已採用觀測資料,每個期間一筆。來源缺少的值會省略,絕不補值。每頁觀測資料筆數可能少於 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 代碼,不在涵蓋範圍內。人口資料沒有最新值路由。每次成功呼叫按一次 Economics 呼叫計費。

印尼與地區 經濟數據 路由未公開。每日 FX 資料可透過以下 API 取得: 外匯 API。

回傳 所有 經濟數據 操作。

此頁面對你有幫助嗎?