世界银行指标 API
世界银行指标 API 提供了约 30,000 个时间序列指标,涵盖 217 个经济体和 78 个区域/收入组合,部分序列可追溯至 1960 年。 无需 API 密钥、无需注册、无已知速率限制 — 直接使用 HTTPS GET 请求。
基础 URL:https://api.worldbank.org/v2
始终附加 format=json — 默认响应格式为 XML。
最快路径:内置脚本
对于常见情况(一个或多个国家的一个或多个指标),请运行内置的零依赖脚本(Python 3.8+,仅使用标准库):
python3 scripts/wb_data.py gdp US,JP,CN # 别名 + ISO 代码,最近 5 年
python3 scripts/wb_data.py SP.POP.TOTL BR --date 2000:2024 # 显式指标代码 + 范围
python3 scripts/wb_data.py inflation all --mrv 1 # 所有经济体,最新值
python3 scripts/wb_data.py population WLD,EUU --json # 组合数据,原始 JSON 输出
python3 scripts/wb_data.py --search "renewable energy" # 按关键词查找指标代码
python3 scripts/wb_data.py --aliases # 列出内置指标别名
退出码:0 成功,1 未找到/无数据,2 API 或网络错误。
对于其他情况(国家元数据、按主题/来源查找指标、月度/季度序列或非 Python 环境),请直接调用下面的 API。
核心数据查询
GET https://api.worldbank.org/v2/country/{codes}/indicator/{indicator}?format=json
{codes}— ISO-2 或 ISO-3 国家代码,分号分隔(US;JP;CN), 组合代码(WLD、EUU、HIC...)或all(所有 265 个经济体+组合)。{indicator}— 如NY.GDP.MKTP.CD的指标代码(不区分大小写)。
示例
GET https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD?format=json&mrv=2
[
{"page": 1, "pages": 1, "per_page": 50, "total": 4,
"sourceid": "2", "lastupdated": "2026-07-01"},
[
{"indicator": {"id": "NY.GDP.MKTP.CD", "value": "GDP (current US$)"},
"country": {"id": "US", "value": "United States"},
"countryiso3code": "USA", "date": "2025",
"value": 30769700000000, "unit": "", "obs_status": "", "decimal": 0},
{"...": "每个国家×年一个对象,最新优先"}
]
]
响应结构:一个包含 2 个元素的 JSON 数组 — [0] 是分页元数据,
[1] 是数据数组(若无匹配则为 null)。value 在国家未报告的年份为 null。数据行按每个国家的最新日期优先排序。
时间和分页参数
| 参数 | 含义 |
|---|---|
date=2020 / date=2000:2024 | 单一年份或范围。月度 2025M01:2025M06,季度 2024Q1:2025Q4(适用于少数月度/季度数据源) |
mrv=N | 每个国家最近的 N 个值(覆盖 date) |
mrnev=N | 每个国家最近 N 个非空值 — 用于获取“最新可用”值,因为许多序列滞后 1-2 年 |
gapfill=Y | 与 mrv 一起使用:用最后已知值向前填充缺失年份 |
per_page=N(默认 50) | 每页行数;大值(如 20000)也能正常工作 — 设置高值可避免分页 |
page=N | 页码;当 page < pages 时循环,参考元数据 |
footnote=y | 为每个数据点添加 footnote 字段 |
一次调用多个指标需要显式指定数据源:
/country/BR/indicator/NY.GDP.MKTP.CD;SP.POP.TOTL?source=2&format=json
(数据源 2 = 世界发展指标,包含大多数常用序列)。
最常用的指标代码(均已在线验证)
| 代码 | 指标 |
|---|---|
NY.GDP.MKTP.CD | GDP(当前美元) |
NY.GDP.MKTP.KD.ZG | GDP 增长率(年百分比) |
NY.GDP.PCAP.CD | 人均 GDP(当前美元) |
NY.GNP.PCAP.CD | 人均 GNI,阿特拉斯法(当前美元) |
SP.POP.TOTL | 总人口 |
FP.CPI.TOTL.ZG | 通胀,消费者价格(年百分比) |
SL.UEM.TOTL.ZS | 失业率(占劳动力百分比,ILO) |
SP.DYN.LE00.IN | 出生时预期寿命(年) |
SI.POV.GINI | 基尼指数 |
SI.POV.DDAY | 贫困发生率(每天 $3.00,占人口百分比) |
EN.GHG.CO2.PC.CE.AR5 | 人均 CO2 排放量(吨 CO2 当量) |
IT.NET.USER.ZS | 互联网用户(占人口百分比) |
NE.EXP.GNFS.ZS | 商品和服务出口(占 GDP 百分比) |
BX.KLT.DINV.WD.GD.ZS | 外国直接投资净流入(占 GDP 百分比) |
PA.NUS.FCRF | 官方汇率(当地货币/美元) |
SP.URB.TOTL.IN.ZS | 城市人口(占总人口百分比) |
按主题分组的大约 100 多个已验证代码见 references/indicators.md —
当需要的序列不在此表中时,请阅读该文件。要按关键词搜索,请使用脚本的 --search 或 references/endpoints.md 中的发现端点(API 没有服务器端文本搜索)。
国家代码和组合
国家:ISO-2(US)或 ISO-3(USA)均可。值得记住的组合代码:
WLD 世界,EUU 欧盟,EMU 欧元区,HIC/UMC/LMC/LIC 收入组,EAS 东亚和太平洋,ECS 欧洲和中亚,
LCN 拉丁美洲和加勒比,MEA 中东和北非,
SAS 南亚,SSF 撒哈拉以南非洲,NAC 北美。
country/all 返回经济体和组合混合在一起(每年 265 行)。要仅保留真实国家,请一次性获取
/v2/country?format=json&per_page=400,并剔除 region.value == "Aggregates" 的条目。
国家元数据(地区、收入水平、首都、坐标):
GET https://api.worldbank.org/v2/country/JPN?format=json
GET https://api.worldbank.org/v2/country?incomeLevel=LIC&format=json&per_page=100
代码示例
import requests
def wb_series(indicator: str, countries: str = "all", **params) -> list[dict]:
"""获取世界银行序列;返回数据点的扁平列表。"""
url = f"https://api.worldbank.org/v2/country/{countries}/indicator/{indicator}"
r = requests.get(url, params={"format": "json", "per_page": 20000, **params}, timeout=30)
r.raise_for_status()
body = r.json()
if "message" in body[0]: # API 错误以 HTTP 200 返回
raise ValueError(body[0]["message"][0]["value"])
return body[1] or []
gdp = wb_series("NY.GDP.MKTP.CD", "US;JP;CN", date="2015:2024")
latest = wb_series("SP.DYN.LE00.IN", "all", mrnev=1)
const url = "https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD"
+ "?format=json&mrv=5&per_page=1000";
const [meta, rows] = await (await fetch(url)).json();
if (meta.message) throw new Error(meta.message[0].value);
for (const r of rows ?? []) console.log(r.country.value, r.date, r.value);
错误
错误以 HTTP 200 返回,并附带消息信封 — 请始终检查:
[{"message": [{"id": "120", "key": "Invalid value",
"value": "The provided parameter value is not valid"}]}]
120— 无效的国家或指标代码(也适用于世界银行未覆盖的经济体,例如台湾在任何代码下都没有数据)。175— 指标存在但其数据已被删除或归档(例如旧的 CO2 序列EN.ATM.CO2E.PC→ 使用EN.GHG.*替换;整个《营商环境报告》数据源已归档)。请搜索后续代码。- 偶尔会出现瞬态 HTML“Request Error”页面代替 JSON — 在视为失败前重试一次。
实用技巧
- 对于“最新数值”,优先使用
mrnev=1而非mrv=1— 大多数序列滞后一到两年,因此mrv=1通常返回最新年份且value: null。 - 将
per_page设高(例如20000),几乎无需分页;all国家 × 一年只有 265 行。 - 元数据中的
total统计的是国家×时期插槽的数量,包括空值。 - 本地化名称:在
/v2后插入语言代码 —/v2/zh/country/CN/indicator/...(支持:en、es、fr、ar、zh)。 仅标签会被翻译;代码和值保持不变。 - 数据修订大约每月一次;元数据中的
lastupdated会告诉你数据源的刷新日期。 - 年度数据是常态。月度/季度数据仅存在于少数数据源(全球经济监测
source=15,季度债务source=20/22/23)— 参见references/endpoints.md。
有关完整端点目录(指标列表、主题、数据源、地区、收入水平、贷款类型、语言、月度/季度数据),请阅读 references/endpoints.md;有关按主题分组的约 100 多个已验证指标代码,请阅读 references/indicators.md。