CommunityPesquisa e Análise de Dadosgithub.com

World Bank Indicators API (Habilidade de Agente AI)

Habilidade para agente AI que ensina agentes de IA a buscar PIB, população, inflação e cerca de 30.000 outros indicadores de desenvolvimento usando a API gratuita do Banco Mundial (sem chave de API).

O que é World Bank Indicators API (Habilidade de Agente AI)?

Esta habilidade capacita agentes de IA (como Claude Code, Cursor ou Codex) a consultar e processar eficientemente a vasta base de dados de indicadores de desenvolvimento do Banco Mundial, que contém aproximadamente 30.000 séries temporais para 217 economias e 78 agregados regionais, algumas desde 1960. A API é totalmente gratuita e não requer chave, inscrição ou limites de taxa documentados — basta uma requisição HTTPS GET. A habilidade fornece um script Python integrado sem dependências externas (stdlib apenas), facilitando o uso comum com aliases para os indicadores mais populares (PIB, população, inflação). Para cenários mais avançados — como metadados de países, descoberta de indicadores por tópico, séries mensais/trimestrais ou ambientes não-Python — o agente pode chamar a API diretamente seguindo os parâmetros e regras documentados. Inclui dicas práticas para lidar com respostas paginadas, valores nulos, localização em vários idiomas e mensagens de erro, garantindo consultas robustas e precisas. A habilidade também referencia arquivos complementares com mais de 100 códigos de indicadores verificados por tópico e endpoints de descoberta.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add NanookAI/worldbank-api

Installed? Explore more Pesquisa e Análise de Dados skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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...), ou all (todos os 265 países+agregados).
  • {indicador} — um código de indicador como NY.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âmetroSignificado
date=2020 / date=2000:2024Ano único ou intervalo. Mensal 2025M01:2025M06, trimestral 2024Q1:2025Q4 para as poucas fontes mensais/trimestrais.
mrv=NN valores mais recentes por país (substitui date)
mrnev=NN valores não vazios mais recentes — use para "último disponível", já que muitas séries têm defasagem de 1–2 anos
gapfill=YCom 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=NNúmero da página; faça loop enquanto page < pages nos metadados
footnote=yAdiciona 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ódigoIndicador
NY.GDP.MKTP.CDPIB (US$ correntes)
NY.GDP.MKTP.KD.ZGCrescimento do PIB (% anual)
NY.GDP.PCAP.CDPIB per capita (US$ correntes)
NY.GNP.PCAP.CDRNB per capita, método Atlas (US$ correntes)
SP.POP.TOTLPopulação total
FP.CPI.TOTL.ZGInflação, preços ao consumidor (% anual)
SL.UEM.TOTL.ZSDesemprego (% da força de trabalho, OIT)
SP.DYN.LE00.INExpectativa de vida ao nascer (anos)
SI.POV.GINIÍndice de Gini
SI.POV.DDAYProporção de pobres com $3,00/dia (% da população)
EN.GHG.CO2.PC.CE.AR5Emissões de CO2 per capita (t CO2e)
IT.NET.USER.ZSUsuários de internet (% da população)
NE.EXP.GNFS.ZSExportações de bens e serviços (% do PIB)
BX.KLT.DINV.WD.GD.ZSEntradas líquidas de IDE (% do PIB)
PA.NUS.FCRFTaxa de câmbio oficial (moeda local por US$)
SP.URB.TOTL.IN.ZSPopulaçã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 CO2 EN.ATM.CO2E.PC → use as substituições EN.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=1 a mrv=1 para "o número mais recente" — a maioria das séries tem defasagem de um a dois anos, então mrv=1 frequentemente retorna o ano mais novo com value: null.
  • Defina per_page alto (ex.: 20000) e você quase nunca precisará paginar; all países × um ano tem apenas 265 linhas.
  • total nos 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; lastupdated nos 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 trimestral source=20/22/23) — veja references/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.

Habilidades Relacionadas