📖 Documentação da API

Introdução

A API REST do Score de Cidades fornece dados socioeconômicos de 5.570 municípios brasileiros, 27 estados e mais de 20.000 bairros. Os dados integram IBGE, RAIS, Anatel, Banco Central, Ministério da Saúde e Receita Federal.

Todas as respostas são em JSON. A API é versionada — use sempre o prefixo /v1/.

🔑 Autenticação

O plano Free não exige autenticação — o rate limit é aplicado por IP. Os planos Starter e Pro exigem uma chave de API no header x-api-key.

# Plano Free (sem chave)
curl https://api.scorecidades.com.br/v1/cidade/campinas

# Planos Starter/Pro
curl -H "x-api-key: sk_live_SEU_TOKEN" \
  https://api.scorecidades.com.br/v1/cidade/campinas

📊 Limites de Uso

Ao exceder o limite, a API retorna status 429 Too Many Requests.

⚠️ Erros

// Exemplo de resposta de erro
{
  "error": "rate_limited",
  "message": "Limite de 100 req/dia excedido. Reset às 00:00 UTC.",
  "reset_at": "2026-04-11T00:00:00Z"
}

GET /v1/cidade/{slug}Free

Retorna dados básicos de um município. O slug é o nome do município em lowercase com hífens (ex: sao-paulo, belo-horizonte).

Parâmetros de query

Exemplo

curl https://api.scorecidades.com.br/v1/cidade/curitiba

{
  "slug": "curitiba",
  "nome": "Curitiba",
  "uf": "PR",
  "regiao": "Sul",
  "populacao": 1948626,
  "area_km2": 435.27,
  "idh": 0.823,
  "pib_per_capita": 48320,
  "score_investidor": 84.0,
  "alfabetizacao": 97.3,
  "capital": true
}

GET /v1/rankingFree

Retorna o ranking de municípios por IDH, PIB per capita ou Score do Investidor.

GET /v1/estadosFree

Lista todos os 27 estados brasileiros com dados básicos.

GET /v1/cidadesStarter

Lista municípios com filtros avançados.

GET /v1/compararStarter

Compara dois municípios lado a lado com delta percentual entre os indicadores.

curl -H "x-api-key: sk_live_SEU_TOKEN" \
  "https://api.scorecidades.com.br/v1/comparar?a=sao-paulo&b=rio-de-janeiro"

GET /v1/custo-vida/{uf}Starter

Custo de vida das capitais: aluguel 1 quarto, cesta básica e gasolina. Cobertura: 27 capitais.

GET /cidade/{slug}/economiaPro

PIB setorial (agropecuária, indústria, serviços, administração pública) e dados de crédito bancário (ESTBAN/BCB 2025).

GET /cidade/{slug}/mercado-trabalhoPro

Dados da RAIS 2022: salário médio mensal e percentual de trabalhadores com ensino superior.

GET /cidade/{slug}/segurancaPro

Homicídios absolutos e por 100k habitantes — SIM/Ministério da Saúde 2022.

GET /cidade/{slug}/conectividadePro

Percentual de conexões de banda larga fixa via fibra óptica — Anatel 2024.

GET /v1/bairros/{slug}Pro

Dados de CNPJ por bairro agregados da Receita Federal. Disponível para as 50 principais cidades brasileiras.

🌐 Suporte a Idiomas

Todos os endpoints aceitam o parâmetro ?lang= para retornar os dados em diferentes idiomas.

curl -H "x-api-key: sk_live_SEU_TOKEN" \
  "https://api.scorecidades.com.br/v1/cidade/sao-paulo?lang=zh"