API pública
Resultados eleitorais brasileiros no nível de bairro — a granularidade que o TSE publica por seção e que o Mapa Eleitoral agrega, normaliza e casa com as malhas territoriais. Pensada para órgãos públicos, imprensa, universidades e empresas.
Como obter uma chave
As chaves são emitidas manualmente, uma por organização. Escreva para [email protected] dizendo quem é a organização, o que pretende construir e o volume estimado de consultas por dia. Não há auto-cadastro.
Autenticação
Envie a chave no header Authorization. O header X-API-Key também é aceito. A chave não pode ir na query string — URL vaza em log de servidor, histórico e Referer.
curl -H "Authorization: Bearer mapa_sua_chave_aqui" \
"https://www.mapaeleitoral.com.br/api/public/v1/cobertura?cidade=rio"Limites
Cada chave tem uma quota diária, informada na emissão. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (epoch em segundos). Ao esgotar, a API responde 429 com Retry-After. A janela reinicia à meia-noite UTC.
Formato da resposta
Todas as respostas de sucesso têm o mesmo envelope: os registros em dados e o contexto da consulta em meta. Erros trazem error (mensagem legível) e code (estável, para tratar em código).
{
"dados": [
{ "bairro": "COPACABANA", "votos": 42150, "votos_validos_bairro": 96320,
"pct_do_candidato": 2.3, "pct_do_bairro": 43.8 }
],
"meta": { "fonte": "Tribunal Superior Eleitoral (TSE)", "versao": "v1",
"cidade": "rio", "ano": "2024", "total_votos": 1861856 }
}Endpoints
GET/cobertura
O que existe
Ponto de partida: cada combinação de cidade, ano e cargo com dados de bairro, e quantos bairros distintos têm voto. Aceita os filtros opcionais cidade e ano.
curl -H "Authorization: Bearer $CHAVE" "https://www.mapaeleitoral.com.br/api/public/v1/cobertura?cidade=rio"GET/candidatos
Quem concorreu
Candidatos de um partido num recorte. Serve para descobrir a grafia exata do nome de urna que /votos-por-bairro exige. Parâmetros: cidade, ano, cargo, partido e turno (opcional, padrão 1).
curl -H "Authorization: Bearer $CHAVE" \
"https://www.mapaeleitoral.com.br/api/public/v1/candidatos?cidade=rio&ano=2024&cargo=prefeito&partido=PSD"GET/votos-por-bairro
Onde o candidato foi bem
O núcleo da API. Atenção aos dois percentuais, que respondem perguntas diferentes:
pct_do_candidato— quanto aquele bairro pesa no total do candidato. Soma 100 entre os bairros.pct_do_bairro— a fatia do candidato entre os votos válidos daquele bairro. É o número que colore o mapa.
O campo bairro já vem na grafia do GeoJSON, então casa direto com as malhas publicadas pelo site.
curl -H "Authorization: Bearer $CHAVE" \
"https://www.mapaeleitoral.com.br/api/public/v1/votos-por-bairro?cidade=rio&ano=2024&cargo=prefeito\
&partido=PSD&candidato=EDUARDO%20PAES"GET/bairro
Quem venceu neste bairro
A visão transposta: todos os candidatos de um bairro, ordenados por votação. Acento e caixa no parâmetro bairro são indiferentes.
curl -H "Authorization: Bearer $CHAVE" \
"https://www.mapaeleitoral.com.br/api/public/v1/bairro?cidade=rio&ano=2024&bairro=Copacabana"Especificação
O contrato completo está em OpenAPI 3.1, aberto e sem necessidade de chave: /api/public/v1/openapi.json. Dá para gerar cliente com qualquer ferramenta do ecossistema.
Dados e atribuição
A fonte primária é o Tribunal Superior Eleitoral. O que a API acrescenta é a agregação por bairro e a normalização dos nomes contra as malhas territoriais — trabalho que não existe no dado bruto. Ao publicar análises, cite o TSE como fonte dos dados e o Mapa Eleitoral como origem do recorte por bairro.
Nenhum dado pessoal de eleitor é coletado ou exposto: o menor recorte é a seção eleitoral agregada em bairro, como o TSE publica. A API também não expõe documentos de candidatos.
Dúvidas ou um caso de uso que os endpoints atuais não cobrem? [email protected]. Veja também o projeto.