Para desenvolvedores

API do LulaHub · v1.1.0

Dados do 1º turno de 2026 por cidade e bairro, a prioridade de cada lugar (onde mais gente não escolheu ninguém) e o perfil estimado de quem não votou. Só dados agregados e públicos (TSE e IBGE); nenhum dado de pessoa.

Endereço: https://squid.sts.lol/api/v1 · Especificação OpenAPI 3.1: openapi.json (serve para gerar cliente ou abrir no Postman/Insomnia).

Autenticação

Todo pedido de dados exige uma chave de API. Sem chave, ou com chave errada ou revogada, a resposta é 401 e nenhum dado sai. Só esta documentação, a especificação (openapi.json) e /saude abrem sem chave, e nenhuma delas traz dados.

A chave tem o formato lh_ + 48 caracteres e vai em todo pedido, no cabeçalho Authorization: Bearer lh_… (ou X-API-Key: lh_…).
Quem cria é a equipe do LulaHub: uma chave por app, com limite de pedidos por minuto. Ela aparece uma vez só, na criação; o servidor guarda só o hash.
Guarde num cofre de segredos, nunca no código nem no navegador. Vazou? Peça para revogar: ela para de funcionar na hora.

Sem chave

$ curl -i https://squid.sts.lol/api/v1/lugares

HTTP/1.1 401 Unauthorized
{"erro":{"codigo":"sem_chave","mensagem":"Envie a chave no cabeçalho Authorization: Bearer <chave> ou X-API-Key."}}

Começar

Peça uma chave à equipe do LulaHub.
Chame a API do seu servidor, com a chave no cabeçalho. A API não libera CORS: chamada direta do navegador exporia a chave.

curl -H "Authorization: Bearer $LULAHUB_CHAVE" \
  "https://squid.sts.lol/api/v1/lugares?tipo=bairro&uf=RJ&prioridade=alta&limite=20"

const resposta = await fetch(
  `https://squid.sts.lol/api/v1/lugares/${encodeURIComponent("RJ-58777|MOSELA")}`,
  { headers: { Authorization: `Bearer ${process.env.LULAHUB_CHAVE}` } },
);
if (resposta.status === 429) {
  // passou do limite: espere o tempo de Retry-After (em segundos)
}
const lugar = await resposta.json();
const idosos = lugar.perfil?.idade.find((g) => g.nome === "70+");

Limites e paginação

Cada chave tem um limite de pedidos por minuto (padrão: 120). Passou, a resposta é 429 com Retry-After.
/lugares é paginado: limite (até 500) e pagina. A resposta traz total; para ler tudo, avance a página até pagina × por_pagina ≥ total.
Os dados mudam pouco (o resultado do 1º turno é fixo; os perfis são recalculados quando sai dado novo). Guarde em cache do seu lado.

Endpoints

GET`/api/v1/lugares`

Lista cidades e bairros

Cidades (todas as 5.571) e bairros (nas cidades com 50 mil eleitores ou mais), com o resultado do 1º turno de 2026 para presidente. Por padrão vem quem tem mais gente sem votar primeiro.

Parâmetro	Onde	Valores	Descrição
tipo	query	cidade \| bairro	Só cidades ou só bairros. Sem o parâmetro, vêm os dois.
uf	query	string	Sigla do estado.
cidade	query	string	Id de uma cidade: traz ela e os bairros dela.
prioridade	query	alta \| media \| normal	Prioridade calculada pelo LulaHub.
ordem	query	fora \| taxa \| nome, padrão fora	fora = mais gente sem votar (número) primeiro; taxa = maior proporção primeiro; nome = alfabética.
limite	query	integer, 1–500, padrão 100	Itens por página.
pagina	query	integer, 1–, padrão 1	Página, a partir de 1.

Respostas

200 Página de lugares.
400 Parâmetro inválido.
401 Sem chave, ou chave inválida ou revogada.
429 Passou do limite de pedidos por minuto da chave. Veja o cabeçalho Retry-After.

GET`/api/v1/lugares/{id}`

Um lugar, com o perfil de quem não votou

Resultado do lugar e o perfil estimado de quem não votou (idade, gênero, escolaridade, cor ou raça, religião e locais de votação). Id de bairro tem "|": codifique como %7C.

Parâmetro	Onde	Valores	Descrição
id *	caminho	string	Id da cidade (RJ-58777) ou do bairro (RJ-58777\|MOSELA, na URL RJ-58777%7CMOSELA).

Respostas

200 O lugar. perfil vem null quando ainda não foi calculado.
400 Id em formato inválido.
401 Sem chave, ou chave inválida ou revogada.
404 Lugar não existe.
429 Passou do limite de pedidos por minuto.

curl -H "Authorization: Bearer $LULAHUB_CHAVE" \
  "https://squid.sts.lol/api/v1/lugares/RJ-58777%7CMOSELA"

Exemplo de resposta (Mosela, Petrópolis/RJ; listas encurtadas)

{
  "id": "RJ-58777|MOSELA", "tipo": "bairro", "nome": "Mosela",
  "cidade_id": "RJ-58777", "municipio": "Petrópolis", "uf": "RJ",
  "aptos": 11038, "abstencoes": 2772, "brancos": 207, "nulos": 252,
  "fora": 3231, "taxa_fora": 29.3, "prioridade": "media",
  "lat": -22.494432, "lng": -43.200426,
  "perfil": {
    "v": 1, "aptos": 11038, "abstencoes": 2772, "brancos": 207, "nulos": 252,
    "eleitores": 11046, "previsto": 2879,
    "idade": [
      { "nome": "18-24", "eleitores": 865, "faltou": 157 },
      { "nome": "70+", "eleitores": 2048, "faltou": 1386 }
    ],
    "genero": [{ "nome": "mulheres", "eleitores": 5920, "faltou": 1516 }],
    "escolaridade": [{ "nome": "fundamental", "eleitores": 3736, "faltou": 1166 }],
    "grupos": [{ "nome": "mulheres · 70+ · fundamental", "faltou": 455, "taxa": 75 }],
    "raca": [{ "nome": "Branca", "faltou": 1944 }, { "nome": "Parda", "faltou": 556 }],
    "religiao": [{ "nome": "Católica", "faltou": 1560 }, { "nome": "Evangélica", "faltou": 679 }],
    "locais": [{
      "nome": "ESCOLA MUNICIPAL SAO JUDAS TADEU", "endereco": "R. MOSELA, 1445",
      "lat": -22.4956041, "lon": -43.2002285, "eleitores": 3104,
      "abstencoes": 851, "pct70": 24.9, "faltou70": 523
    }],
    "censo": { "setores": 32, "moradores": 13690, "pct70": 11.9, "razao": 0.81,
               "raca": [{ "nome": "Branca", "pct": 66 }, { "nome": "Parda", "pct": 23.3 }] }
  },
  "perfil_atualizado_em": "2026-10-08T02:49:44.296+00:00"
}

Campos

Lugar

Campo	Tipo	Descrição
id	string	Cidade: UF-código TSE. Bairro: id da cidade + "\|" + nome normalizado.
tipo	cidade \| bairro
nome	string
cidade_id	string
municipio	string
uf	string
aptos	integer	Eleitores aptos no 1º turno de 2026.
abstencoes	integer	Não foram votar.
brancos	integer
nulos	integer
fora	integer	Não escolheram ninguém: abstenções + brancos + nulos.
taxa_fora	number	fora / aptos, em %.
prioridade	alta \| media \| normal	alta = volume de "fora" entre os 5% maiores, ou proporção entre as 25% maiores com volume acima da mediana.
lat	number \| null	Centro dos locais de votação (só bairros).
lng	number \| null
tem_perfil	boolean	Se já existe perfil calculado (só na lista).

Perfil

Estimativa para grupos, nunca sobre pessoas. Veja o método em /docs/api.

Campo	Tipo	Descrição
v	objeto	Versão do formato.
aptos	integer
abstencoes	integer
brancos	integer
nulos	integer
eleitores	integer	Eleitores no perfil por seção do TSE (pode diferir um pouco de aptos).
previsto	integer	Abstenções que as taxas de 2022 previam, antes do ajuste ao real de 2026.
idade	Grupo[]	Faixas: 16-17, 18-24, 25-34, 35-44, 45-59, 60-69, 70+ (16-17 e 70+ votam por opção).
genero	Grupo[]	mulheres, homens, não informado.
escolaridade	Grupo[]	sem estudo formal, fundamental, médio incompleto, médio completo, superior, não informado.
grupos	array	Os 6 maiores grupos gênero · idade · escolaridade entre quem faltou.
raca	objeto	Cor ou raça de quem faltou (Censo 2022 da vizinhança, por faixa etária). null quando a vizinhança não bate com o eleitorado (veja censo.razao).
religiao	objeto	Religião de quem faltou (Censo 2022 do município, por sexo e idade).
locais	LocalVotacao[]	Locais de votação (só em bairros).
censo	object \| null	Moradores da vizinhança (setores do Censo 2022 mais próximos dos locais de votação do lugar).

Grupo

Campo	Tipo	Descrição
nome	string
eleitores	integer	Eleitores do grupo no lugar (TSE).
faltou	integer	Estimativa de quantos do grupo não foram votar.

Fatia

Campo	Tipo	Descrição
nome	string
faltou	integer	Estimativa de quantos de quem faltou.

LocalVotacao

Campo	Tipo	Descrição
nome	string
endereco	string
lat	number \| null
lon	number \| null
eleitores	integer
abstencoes	integer	Real (TSE).
pct70	number	% dos eleitores do local com 70 anos ou mais (0 a 100).
faltou70	integer	Estimativa de quantos com 70+ não foram votar.

Erros

Todo erro vem como { "erro": { "codigo": "...", "mensagem": "..." } }.

HTTP	codigo	Quando
400	parametro_invalido	Parâmetro fora do formato (a mensagem diz qual).
401	sem_chave / chave_invalida	Faltou a chave, ou ela foi revogada.
404	nao_encontrado	O id não existe.
429	limite	Passou do limite de pedidos por minuto da chave. Espere o Retry-After (60 s).
500	erro_interno	Falha nossa. Tente de novo; se continuar, avise a equipe.

De onde vêm os números

Resultado e prioridade: TSE, resultado por seção do 1º turno de 2026 (presidente). Bairro é o do local de votação de cada seção, nas cidades com 50 mil eleitores ou mais.
Idade, gênero e escolaridade de quem faltou: eleitorado de cada seção (TSE, 2026) × taxa real de abstenção de cada grupo no município no 1º turno de 2022 (TSE), com um ajuste por lugar para somar a abstenção real de 2026. previsto mostra o quanto as taxas de 2022 acertavam antes do ajuste.
Cor ou raça: Censo 2022, setores cujo local de votação mais próximo é do lugar, por faixa etária (15–29, 30–59, 60+), aplicado a quem faltou de cada idade. O TSE não serve: 71% dos eleitores não declararam cor. Quando a vizinhança não bate com o eleitorado (censo.razao fora de 0,3–2,5), raca vem null: em cerca de 11% dos lugares.
Religião: Censo 2022 do município, por sexo e idade. É a parte mais fraca: o IBGE não publica religião por setor.
Locais de votação: a pessoa vota perto de onde morava quando tirou ou atualizou o título; o local indica a região onde ela mora.

Uso responsável

O perfil é estimativa para grupos. Não apresente como contagem exata e não diga que uma pessoa ou um grupo "votou" de tal jeito: o voto é secreto.
Não cruze estes dados com dados de pessoas (listas, cadastros, CPF, telefone) para deduzir o voto de alguém. Opinião política é dado sensível na LGPD.
Nada de disparo em massa, robôs ou perfis falsos (regras do TSE). Transporte de eleitores no dia da eleição é crime (Lei 6.091/74); levar a própria família pode.

Versões

Mudanças compatíveis (campo novo, filtro novo) mantêm /api/v1 e sobem a versão no cabeçalho X-LulaHub-API. Mudança que quebra cliente vira /api/v2, com aviso antes. O perfil tem o campo v com a versão do formato.