人口历史数据 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 调用计费。
印度尼西亚和地区级经济数据路由不对外开放。日频外汇数据可通过以下 API 获取: 外汇 API。
返回 所有经济数据操作。
从免费密钥开始
每月赠送 10 美元免费额度,无需绑卡。每月 10 美元免费额度,无需绑卡。
此页面对你有帮助吗?