浏览全部文档

人口历史数据 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 调用计费。

印度尼西亚和地区级经济数据路由不对外开放。日频外汇数据可通过以下 API 获取: 外汇 API。

返回 所有经济数据操作。

此页面对你有帮助吗?