Community研究与数据分析github.com

世界银行API技能

教授AI代理使用免费的世界银行API获取GDP、人口、通胀等约30,000个发展指标(无需API密钥)。

世界银行API技能 是什么?

该技能使AI代理能够通过免费的世界银行API轻松获取约30,000个时间序列发展指标,覆盖217个经济体和78个区域/收入组合,部分数据可追溯至1960年。无需注册或API密钥,仅需简单的HTTPS GET请求。技能提供了一个零依赖的Python脚本(`scripts/wb_data.py`),支持常见用例,如获取一或多个国家的一或多个指标,并内置了别名(如`gdp`、`population`、`inflation`)和搜索功能。对于更复杂的查询,技能详细说明了核心API端点、参数(包括时间范围、分页、最新值、填充)以及常用的指标代码表。最后,技能解释了错误处理机制和实践技巧,如优先使用`mrnev=1`而非`mrv=1`以获取最新有效数据,设置高`per_page`值以简化分页,并支持通过语言代码(如`/v2/zh`)获取本地化标签。该技能兼容Claude Code、Cursor、Codex等主流AI编程代理。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add NanookAI/worldbank-api

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

世界银行指标 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.CDGDP(当前美元)
NY.GDP.MKTP.KD.ZGGDP 增长率(年百分比)
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。

相关技能