World Bank Indicators API

Habilidad para que agentes de IA obtengan datos de PIB, población, inflación y otros ~30,000 indicadores de desarrollo mediante la API gratuita del Banco Mundial (sin clave API).

¿Qué es World Bank Indicators API?

Esta habilidad permite a agentes de IA acceder a los ~30,000 indicadores de series temporales de la API de Indicadores del Banco Mundial, cubriendo 217 economías y 78 agregados regionales, algunos con datos desde 1960. No requiere clave API, registro ni tiene límite de tasa documentado, solo solicitudes HTTPS GET. La habilidad incluye un script Python sin dependencias que simplifica consultas comunes (PIB, población, inflación, etc.) con alias predefinidos y salida JSON o CSV, y también documenta las llamadas directas a la API REST para necesidades más complejas como metadatos de países, indicadores por tema, series mensuales/trimestrales o entornos que no sean Python. Está diseñada tanto para agentes que ejecutan scripts localmente como para aquellos que integran la API directamente, ofreciendo ejemplos en Python y JavaScript, manejo de errores y parámetros de paginación y filtrado temporal. Su utilidad principal es proporcionar datos macroeconómicos y de desarrollo de manera fiable y sencilla para análisis, visualizaciones o sistemas de decisión automatizados.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add NanookAI/worldbank-api

Installed? Explore more Investigación y análisis de datos skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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...), o all (los 265 países+agregados).
  • {indicador} — un código de indicador como NY.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ámetroSignificado
date=2020 / date=2000:2024Añ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=YCon 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=NNúmero de página; itera mientras page < pages desde los metadatos
footnote=yAñ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ódigoIndicador
NY.GDP.MKTP.CDPIB (US$ actuales)
NY.GDP.MKTP.KD.ZGCrecimiento del PIB (% anual)
NY.GDP.PCAP.CDPIB per cápita (US$ actuales)
NY.GNP.PCAP.CDINB per cápita, método Atlas (US$ actuales)
SP.POP.TOTLPoblación, total
FP.CPI.TOTL.ZGInflación, precios al consumidor (% anual)
SL.UEM.TOTL.ZSDesempleo (% de la fuerza laboral, OIT)
SP.DYN.LE00.INEsperanza de vida al nacer (años)
SI.POV.GINIÍndice de Gini
SI.POV.DDAYTasa de pobreza a $3.00/día (% de la población)
EN.GHG.CO2.PC.CE.AR5Emisiones de CO2 per cápita (t CO2e)
IT.NET.USER.ZSUsuarios de Internet (% de la población)
NE.EXP.GNFS.ZSExportaciones de bienes y servicios (% del PIB)
BX.KLT.DINV.WD.GD.ZSIED, entradas netas (% del PIB)
PA.NUS.FCRFTipo de cambio oficial (moneda local por US$)
SP.URB.TOTL.IN.ZSPoblació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 CO2 EN.ATM.CO2E.PC → usa los reemplazos EN.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=1 sobre mrv=1 para "el último número" — la mayoría de las series tienen un retraso de uno a dos años, por lo que mrv=1 a menudo devuelve el año más reciente con value: null.
  • Ajusta per_page alto (ej. 20000) y casi nunca necesitarás paginar; all países × un año son solo 265 filas.
  • total en 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; lastupdated en 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 trimestral source=20/22/23) — consulta references/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.

Skills relacionados