人口歷史資料 API 參考
從世界銀行取得單一國家的年度總人口。
economics_ 可透過 REST 或 economics_ MCP 工具呼叫。兩者回傳相同的資料結構,並使用同一份額度。
端點與請求
GET /v1/economics/{country}/population/observationscurl --request GET \
--url "https://api.narwhalapi.com/v1/economics/USA/population/observations?start=2024&limit=100" \
--header "Authorization: Bearer $NARWHAL_API_KEY"MCP 使用工具 economics_ ,並使用下列對應參數。
參數
此操作接受的期間格式是 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_ | 否 | 查詢·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_ | RFC 3339 時間戳記 | 否 | 來源最後更新本頁最新觀測值的時間,精確到整秒,使用 UTC。 |
source | 對象 | 是 | publisher 列出原始發布機構,distributor 為世界銀行世界發展指標(CC BY 4.0)。 |
unit | 字串 | 是 | 固定為 person。 |
frequency | 字串 | 是 | 固定為 annual。 |
observations | 陣列 | 是 | 按時間由早到晚排列的已採用觀測資料,每個期間一筆。來源缺少的值會省略,絕不補值。每頁觀測資料筆數可能少於 limit;請繼續使用 next_cursor,直到其值為 null。 |
observations[].period | 字串 | 是 | 觀測值所代表的官方月份、季度或年份。 |
observations[].first_ | RFC 3339 時間戳記 | 否 | 此 UTC 時間戳記僅在使用 version=first_ 時出現,記錄 Narwhal 首次儲存該期資料的時間(若各項數據分別儲存,則採用最晚的時間);開始擷取前已發布的各期資料,會顯示 Narwhal 首次擷取的時間。 |
observations[].value | 十進位數值字串 | 是 | 年中人口,單位為整數人。統計所有居民,不論其法律身分或國籍。最近幾年可能是推估值。 |
next_ | 字串或 null | 是 | 將此值原樣作為 cursor 傳入,以讀取下一頁;最後一頁為 null。 |
API 錯誤 處理:錯誤碼、額度與重試
400 invalid_— 國家、期間或篩選條件的格式無效,或同時傳送了query as_與of version。400 invalid_— 游標格式錯誤,或是針對其他篩選條件或操作簽發的。cursor 401 invalid_— Bearer 金鑰缺失或被拒絕。api_ key 404 series_— 沒有已核准的觀測值符合請求。not_ found 409 cursor_分頁游標過舊,或其對應的資料已改變。請不帶游標重新開始。expired 429 rate_— 已達到網路或帳戶的短時間視窗限制;請依下列標頭指定的等待時間重試:limit_ exceeded Retry-After。402 insufficient_,您的餘額不足以支付該次呼叫。credits 503 economics_— Narwhal 無法安全提供已接受的發布版本。unavailable
Only a successful data response costs credit. 查看 所有錯誤、標頭與重試規則。
資料時效
此路由預設傳回 Narwhal 目前採用的數列;回應中的 as_ 是最新一筆觀測資料的更新時間。任何金鑰都可使用 as_ 或 version=first_ 讀取較早的資料版本。版本歷史從 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。
回傳 所有 經濟數據 操作。
從免費金鑰開始
每月 10 美元免費額度,無需綁卡。每月 10 美元免費額度,無需綁卡。
此頁面對你有幫助嗎?