API de Indicadores del Banco Mundial
La API de Indicadores del Banco Mundial expone ~30,000 indicadores de series temporales para 217 economías y 78 agregados regionales/de ingresos, algunas series desde 1960. Sin clave API, sin registro, sin límite de tasa documentado — simples solicitudes HTTPS GET.
URL base: https://api.worldbank.org/v2
Siempre añade format=json — el formato de respuesta predeterminado es XML.
Ruta más rápida: script empaquetado
Para el caso común — uno o más indicadores para uno o más países — ejecuta el script empaquetado sin dependencias (Python 3.8+, solo librería estándar):
python3 scripts/wb_data.py gdp US,JP,CN # alias + códigos ISO, últimos 5 años
python3 scripts/wb_data.py SP.POP.TOTL BR --date 2000:2024 # código de indicador explícito + rango
python3 scripts/wb_data.py inflation all --mrv 1 # todas las economías, último valor
python3 scripts/wb_data.py population WLD,EUU --json # agregados, salida JSON cruda
python3 scripts/wb_data.py --search "energía renovable" # busca códigos de indicador por palabra clave
python3 scripts/wb_data.py --aliases # lista los alias de indicadores incluidos
Códigos de salida: 0 éxito, 1 no encontrado / sin datos, 2 error de API o red.
Llama a la API directamente (abajo) para cualquier otra cosa: metadatos de país, descubrimiento de indicadores por tema/fuente, series mensuales/trimestrales o entornos que no sean Python.
Consulta de datos principal
GET https://api.worldbank.org/v2/country/{códigos}/indicator/{indicador}?format=json
{códigos}— códigos de país ISO-2 o ISO-3, separados por punto y coma (US;JP;CN), un código de agregado (WLD,EUU,HIC...), oall(los 265 países+agregados).{indicador}— un código de indicador comoNY.GDP.MKTP.CD(no distingue mayúsculas/minúsculas).
Ejemplo
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},
{"...": "un objeto por país×año, del más reciente al más antiguo"}
]
]
Estructura de la respuesta: un array JSON de 2 elementos — [0] son los metadatos de paginación,
[1] es el array de datos (o null cuando no hay coincidencias). value es null
para los años en que un país no ha reportado. Las filas están ordenadas del más reciente al más antiguo por país.
Parámetros de tiempo y paginación
| Parámetro | Significado |
|---|---|
date=2020 / date=2000:2024 | Año único o rango. Mensual 2025M01:2025M06, trimestral 2024Q1:2025Q4 para las pocas fuentes mensuales/trimestrales. |
mrv=N | Últimos N valores por país (anula date) |
mrnev=N | Últimos N valores no vacíos por país — usa para "último disponible" ya que muchas series tienen un retraso de 1–2 años |
gapfill=Y | Con mrv: rellena hacia adelante los años faltantes con el último valor conocido |
per_page=N (por defecto 50) | Filas por página; valores grandes (ej. 20000) funcionan bien — ajústalo alto para evitar paginación |
page=N | Número de página; itera mientras page < pages desde los metadatos |
footnote=y | Añade un campo footnote a cada punto de datos |
Múltiples indicadores en una sola llamada necesitan una fuente explícita:
/country/BR/indicator/NY.GDP.MKTP.CD;SP.POP.TOTL?source=2&format=json
(fuente 2 = Indicadores de Desarrollo Mundial, hogar de la mayoría de las series comunes).
Códigos de indicador más usados (todos verificados activos)
| Código | Indicador |
|---|---|
NY.GDP.MKTP.CD | PIB (US$ actuales) |
NY.GDP.MKTP.KD.ZG | Crecimiento del PIB (% anual) |
NY.GDP.PCAP.CD | PIB per cápita (US$ actuales) |
NY.GNP.PCAP.CD | INB per cápita, método Atlas (US$ actuales) |
SP.POP.TOTL | Población, total |
FP.CPI.TOTL.ZG | Inflación, precios al consumidor (% anual) |
SL.UEM.TOTL.ZS | Desempleo (% de la fuerza laboral, OIT) |
SP.DYN.LE00.IN | Esperanza de vida al nacer (años) |
SI.POV.GINI | Índice de Gini |
SI.POV.DDAY | Tasa de pobreza a $3.00/día (% de la población) |
EN.GHG.CO2.PC.CE.AR5 | Emisiones de CO2 per cápita (t CO2e) |
IT.NET.USER.ZS | Usuarios de Internet (% de la población) |
NE.EXP.GNFS.ZS | Exportaciones de bienes y servicios (% del PIB) |
BX.KLT.DINV.WD.GD.ZS | IED, entradas netas (% del PIB) |
PA.NUS.FCRF | Tipo de cambio oficial (moneda local por US$) |
SP.URB.TOTL.IN.ZS | Población urbana (% del total) |
~100 códigos más verificados agrupados por tema en references/indicators.md —
léelo siempre que la serie necesaria no esté en esta tabla. Para buscar por palabra clave,
usa --search del script o los endpoints de descubrimiento en
references/endpoints.md (no hay búsqueda de texto en servidor en la API).
Códigos de país y agregados
Países: ISO-2 (US) o ISO-3 (USA) ambos funcionan. Agregados que vale la pena conocer:
WLD Mundo, EUU Unión Europea, EMU Zona Euro, HIC/UMC/LMC/LIC
grupos de ingreso, EAS Asia Oriental y Pacífico, ECS Europa y Asia Central,
LCN América Latina y Caribe, MEA Oriente Medio y Norte de África,
SAS Asia Meridional, SSF África Subsahariana, NAC América del Norte.
country/all devuelve economías y agregados mezclados (265 filas
por año). Para quedarse solo con países reales, obtén
/v2/country?format=json&per_page=400 una vez y elimina las entradas donde
region.value == "Aggregates".
Metadatos de país (región, nivel de ingreso, capital, coordenadas):
GET https://api.worldbank.org/v2/country/JPN?format=json
GET https://api.worldbank.org/v2/country?incomeLevel=LIC&format=json&per_page=100
Ejemplos de código
import requests
def wb_series(indicador: str, paises: str = "all", **params) -> list[dict]:
"""Obtiene una serie del Banco Mundial; devuelve una lista plana de puntos de datos."""
url = f"https://api.worldbank.org/v2/country/{paises}/indicator/{indicador}"
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]: # los errores de la API llegan como 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")
ultimo = 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);
Errores
Los errores llegan como HTTP 200 con un envoltorio de mensaje — compruébalo siempre:
[{"message": [{"id": "120", "key": "Invalid value",
"value": "The provided parameter value is not valid"}]}]
120— código de país o indicador no válido (también se devuelve para economías que el Banco Mundial no cubre, ej. Taiwán no tiene datos bajo ningún código).175— el indicador existe pero sus datos fueron eliminados o archivados (ej. la serie antigua de CO2EN.ATM.CO2E.PC→ usa los reemplazosEN.GHG.*; toda la fuente Doing Business está archivada). Busca un código sucesor.- Ocasionales páginas HTML transitorias de "Error de solicitud" en lugar de JSON — reintenta una vez antes de considerar que es un fallo.
Consejos prácticos
- Prefiere
mrnev=1sobremrv=1para "el último número" — la mayoría de las series tienen un retraso de uno a dos años, por lo quemrv=1a menudo devuelve el año más reciente convalue: null. - Ajusta
per_pagealto (ej.20000) y casi nunca necesitarás paginar;allpaíses × un año son solo 265 filas. totalen los metadatos cuenta los espacios país×período, incluyendo valores nulos.- Nombres localizados: inserta un código de idioma después de
/v2—/v2/es/country/CN/indicator/...(idiomas compatibles:en,es,fr,ar,zh). Solo se traducen las etiquetas; los códigos y valores son idénticos. - Las revisiones de datos llegan aproximadamente cada mes;
lastupdateden los metadatos indica la fecha de actualización de la fuente. - Anual es la norma. Datos mensuales/trimestrales existen solo en unas pocas fuentes
(Monitor Económico Global
source=15, deuda trimestralsource=20/22/23) — consultareferences/endpoints.md.
Para el catálogo completo de endpoints (lista de indicadores, temas, fuentes, regiones,
niveles de ingreso, tipos de préstamo, idiomas, datos mensuales/trimestrales) lee
references/endpoints.md; para ~100 códigos de indicador adicionales verificados por tema
lee references/indicators.md.