API de Indicadores do Banco Mundial
A API de Indicadores do Banco Mundial expõe cerca de 30.000 indicadores de séries temporais para 217 economias e 78 agregados regionais/de renda, algumas séries desde 1960. Sem chave de API, sem cadastro, sem limite de taxa documentado — apenas HTTPS GET simples.
URL base: https://api.worldbank.org/v2
Sempre acrescente format=json — o formato de resposta padrão é XML.
Caminho mais rápido: script incluso
Para o caso comum — um ou mais indicadores para um ou mais países — execute o script incluso sem dependências (Python 3.8+, apenas stdlib):
python3 scripts/wb_data.py gdp US,JP,CN # alias + códigos ISO, últimos 5 anos
python3 scripts/wb_data.py SP.POP.TOTL BR --date 2000:2024 # código explícito + intervalo
python3 scripts/wb_data.py inflation all --mrv 1 # todas as economias, último valor
python3 scripts/wb_data.py population WLD,EUU --json # agregados, saída JSON bruta
python3 scripts/wb_data.py --search "energia renovável" # encontrar códigos por palavra-chave
python3 scripts/wb_data.py --aliases # listar aliases de indicadores
Códigos de saída: 0 sucesso, 1 não encontrado / sem dados, 2 erro de API ou rede.
Chame a API diretamente (abaixo) para qualquer outra coisa: metadados de países, descoberta de indicadores por tópico/fonte, séries mensais/trimestrais ou ambientes não-Python.
Consulta de dados principal
GET https://api.worldbank.org/v2/country/{codigos}/indicator/{indicador}?format=json
{codigos}— códigos de país ISO-2 ou ISO-3, separados por ponto e vírgula (US;JP;CN), um código de agregado (WLD,EUU,HIC...), ouall(todos os 265 países+agregados).{indicador}— um código de indicador comoNY.GDP.MKTP.CD(não diferencia maiúsculas/minúsculas).
Exemplo
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},
{"...": "um objeto por país×ano, do mais recente para o mais antigo"}
]
]
Formato da resposta: um array JSON de 2 elementos — [0] são metadados de paginação, [1] é o array de dados (ou null quando não há correspondência). value é null para anos em que um país não reportou. As linhas são ordenadas do mais recente para o mais antigo por país.
Parâmetros de tempo e paginação
| Parâmetro | Significado |
|---|---|
date=2020 / date=2000:2024 | Ano único ou intervalo. Mensal 2025M01:2025M06, trimestral 2024Q1:2025Q4 para as poucas fontes mensais/trimestrais. |
mrv=N | N valores mais recentes por país (substitui date) |
mrnev=N | N valores não vazios mais recentes — use para "último disponível", já que muitas séries têm defasagem de 1–2 anos |
gapfill=Y | Com mrv: preenche anos faltantes com o último valor conhecido |
per_page=N (padrão 50) | Linhas por página; valores grandes (ex.: 20000) funcionam bem — defina alto para evitar paginação |
page=N | Número da página; faça loop enquanto page < pages nos metadados |
footnote=y | Adiciona um campo footnote a cada ponto de dado |
Vários indicadores em uma chamada precisam de uma fonte explícita:
/country/BR/indicator/NY.GDP.MKTP.CD;SP.POP.TOTL?source=2&format=json
(fonte 2 = World Development Indicators, lar da maioria das séries comuns).
Códigos de indicadores mais usados (todos verificados ao vivo)
| Código | Indicador |
|---|---|
NY.GDP.MKTP.CD | PIB (US$ correntes) |
NY.GDP.MKTP.KD.ZG | Crescimento do PIB (% anual) |
NY.GDP.PCAP.CD | PIB per capita (US$ correntes) |
NY.GNP.PCAP.CD | RNB per capita, método Atlas (US$ correntes) |
SP.POP.TOTL | População total |
FP.CPI.TOTL.ZG | Inflação, preços ao consumidor (% anual) |
SL.UEM.TOTL.ZS | Desemprego (% da força de trabalho, OIT) |
SP.DYN.LE00.IN | Expectativa de vida ao nascer (anos) |
SI.POV.GINI | Índice de Gini |
SI.POV.DDAY | Proporção de pobres com $3,00/dia (% da população) |
EN.GHG.CO2.PC.CE.AR5 | Emissões de CO2 per capita (t CO2e) |
IT.NET.USER.ZS | Usuários de internet (% da população) |
NE.EXP.GNFS.ZS | Exportações de bens e serviços (% do PIB) |
BX.KLT.DINV.WD.GD.ZS | Entradas líquidas de IDE (% do PIB) |
PA.NUS.FCRF | Taxa de câmbio oficial (moeda local por US$) |
SP.URB.TOTL.IN.ZS | População urbana (% do total) |
~100 códigos verificados a mais agrupados por tópico em references/indicators.md —
leia-o sempre que a série necessária não estiver nesta tabela. Para buscar por
palavra-chave, use a opção --search do script ou os endpoints de descoberta em
references/endpoints.md (não há busca textual no servidor na API).
Códigos de países e agregados
Países: ISO-2 (US) ou ISO-3 (USA) ambos funcionam. Agregados que vale a pena
conhecer: WLD Mundo, EUU União Europeia, EMU Zona do Euro, HIC/UMC/LMC/LIC
grupos de renda, EAS Leste Asiático e Pacífico, ECS Europa e Ásia Central,
LCN América Latina e Caribe, MEA Oriente Médio e Norte da África,
SAS Sul da Ásia, SSF África Subsaariana, NAC América do Norte.
country/all retorna economias e agregados misturados (265 linhas
por ano). Para manter apenas países reais, faça uma requisição a
/v2/country?format=json&per_page=400 uma vez e remova entradas onde
region.value == "Aggregates".
Metadados de país (região, nível de renda, 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
Exemplos de código
import requests
def wb_series(indicador: str, paises: str = "all", **params) -> list[dict]:
"""Busca uma série do Banco Mundial; retorna uma lista plana de pontos de dados."""
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]: # erros da API vêm 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")
utimo = 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, linhas] = await (await fetch(url)).json();
if (meta.message) throw new Error(meta.message[0].value);
for (const r of linhas ?? []) console.log(r.country.value, r.date, r.value);
Erros
Erros retornam como HTTP 200 com um envelope de mensagem — sempre verifique:
[{"message": [{"id": "120", "key": "Invalid value",
"value": "The provided parameter value is not valid"}]}]
120— código de país ou indicador inválido (também retornado para economias não cobertas pelo Banco Mundial, ex.: Taiwan não tem dados em nenhum código).175— indicador existe, mas seus dados foram deletados ou arquivados (ex.: a antiga série de CO2EN.ATM.CO2E.PC→ use as substituiçõesEN.GHG.*; toda a fonte Doing Business está arquivada). Procure um código sucessor.- Ocasionalmente, páginas HTML transitórias de "Erro de Requisição" em vez de JSON — tente novamente uma vez antes de tratar como falha.
Dicas práticas
- Prefira
mrnev=1amrv=1para "o número mais recente" — a maioria das séries tem defasagem de um a dois anos, entãomrv=1frequentemente retorna o ano mais novo comvalue: null. - Defina
per_pagealto (ex.:20000) e você quase nunca precisará paginar;allpaíses × um ano tem apenas 265 linhas. totalnos metadados conta slots país×período, incluindo valores nulos.- Nomes localizados: insira um código de idioma após
/v2—/v2/zh/country/CN/indicator/...(suportados:en,es,fr,ar,zh). Apenas rótulos são traduzidos; códigos e valores são idênticos. - As revisões de dados chegam aproximadamente mensalmente;
lastupdatednos metadados informa a data de atualização da fonte. - Anual é a norma. Mensal/trimestral existe apenas em algumas fontes (Global
Economic Monitor
source=15, dívida trimestralsource=20/22/23) — vejareferences/endpoints.md.
Para o catálogo completo de endpoints (lista de indicadores, tópicos, fontes,
regiões, níveis de renda, tipos de empréstimo, idiomas, dados mensais/trimestrais)
leia references/endpoints.md; para mais ~100 códigos de indicadores verificados
por tópico leia references/indicators.md.