TSE: candidatos e bens declarados

Candidatos e bens declarados das eleições de 2018, 2020, 2022 e 2024, por estado, a partir dos dados abertos do TSE. Uma execução baixa o arquivo oficial da eleição escolhida e devolve as candidaturas (ou os bens) de um estado, com filtros por cargo, partido, nome, município e valor.

Fonte: Tribunal Superior Eleitoral (TSE), Portal de Dados Abertos, licença Creative Commons Attribution (CC-BY). Este Actor não é do TSE nem tem ligação com ele. Confira na fonte antes de usar em reportagem, decisão ou publicação.

O que devolve

tipo: candidatos: um registro por candidatura: ano, turno, UF, município (ou unidade eleitoral), cargo, sequencial do candidato, número na urna, nome de registro e de urna, partido, federação, coligação, situação da candidatura, situação na totalização (eleito, não eleito, suplente...), ano de nascimento, gênero, grau de instrução, estado civil, ocupação e a URL do arquivo.

tipo: bens: um registro por bem declarado: quem declarou (nome, cargo, partido, situação), tipo do bem, descrição, valor em reais, data da última atualização e a URL do arquivo.

Exemplo de um bem (valores ilustrativos; o formato é o real):

{
  "ano": 2024,
  "uf": "AC",
  "municipio": "PORTO ACRE",
  "sequencialCandidato": "10002172097",
  "candidato": "NOME DE REGISTRO",
  "nomeUrna": "NOME DE URNA",
  "cargo": "VEREADOR",
  "partido": "PXX",
  "situacaoTotalizacao": "ELEITO",
  "ordemBem": 1,
  "tipoBem": "Veículo automotor terrestre: caminhão, automóvel, moto, etc.",
  "descricao": "Caminhonete S10 LT FS2, Placa ***, RENAVAM ***, Ano Fab. 2013, Cor prata",
  "valor": 70000.0,
  "atualizadoEm": "2026-07-07",
  "arquivoUrl": "https://cdn.tse.jus.br/estatistica/sead/odsele/bem_candidato/bem_candidato_2024.zip"
}

Dado pessoal: o que NÃO sai

O arquivo do TSE traz, para quase todos os candidatos, CPF, título de eleitor, data de nascimento completa, cor/raça e nome social. Isso não é devolvido: o Actor lê esses campos para filtrar e os descarta. Da data de nascimento sai só o ano. O e-mail também não sai (no arquivo de 2022 não havia nenhum preenchido).

O que sai é o que identifica a candidatura: nome de registro, nome de urna, número, cargo, partido, gênero, grau de instrução, estado civil e ocupação. Nome de candidato é informação de registro eleitoral público; mesmo assim, você é responsável por usar o dado de forma lícita e conforme a LGPD.

A descrição dos bens é texto livre do declarante e pode trazer placa e RENAVAM de veículos ou CPF de terceiros. Com mascararDadosPessoais ligado (o padrão), CPF vira ***.456.789-** e placa e RENAVAM viram ***. A máscara usa padrões de texto e pode deixar passar um formato fora do comum; em 157.874 bens de São Paulo em 2024 não sobrou CPF, placa nem RENAVAM reconhecível (conferido em 2026-11-04).

Entrada

Campo	Obrigatório	Padrão	O que faz
ano	sim	2022	2018, 2020, 2022 ou 2024
tipo	sim	candidatos	candidatos ou bens
uf	sim	AP	Sigla do estado. BR traz presidente e vice nas eleições gerais
cargo	não	todos	Parte do nome do cargo: governador, deputado federal, prefeito, vereador...
partido	não	todos	Sigla exata do partido
nome	não	todos	Parte do nome de registro ou de urna (3 letras ou mais)
municipio	não	todos	Parte do nome do município. Útil em 2020 e 2024
apenasEleitos	não	false	Só quem o TSE marca como eleito (inclui por QP e por média)
valorMinimo	não	sem mínimo	Só para bens: descarta bens abaixo desse valor
mascararDadosPessoais	não	true	Máscara de CPF, placa e RENAVAM no texto
limite	não	20	Teto de 10.000 registros

Os filtros de cargo, partido, nome, município e apenasEleitos valem também para bens: valem para o candidato dono do bem.

Preço

Cobrança por evento. O preço em vigor aparece sempre na página do Actor.

Evento	Preço
Início de cada execução	US$ 0,002
Cada registro devolvido	US$ 0,001 (US$ 1,00 por mil)

Vinte registros, o limite padrão, custariam US$ 0,022. Mil registros, US$ 1,002.

Limites

• Cada execução baixa o ZIP inteiro da eleição escolhida e corta o estado depois: 2018 e 2022 são de 4 a 6 MB; 2020 e 2024 são de 44 a 85 MB. Para bens, baixa também o ZIP de candidatos (para ligar o bem ao candidato). Por isso a execução de 2024 leva alguns segundos mesmo sem resultado.
• Só 2018, 2020, 2022 e 2024. Anos anteriores (2016 e antes) não estão incluídos; 2016 tem 140 MB.
• Só candidaturas e bens. Doações, prestação de contas e votos por seção não fazem parte desta versão.
• Teto de 10.000 registros por execução.
• Um filtro sem resultado não é erro: a execução termina com a mensagem "Nenhum registro encontrado para esses filtros".
• O TSE atualiza os arquivos; os números mudam. Medições de 2026-11-04 (nesta máquina e em Docker com 256 MB): 2024 São Paulo, 10.000 bens, 118 MB de pico e cerca de 3 minutos; 10.000 candidatos, 66 MB de pico e cerca de 2,5 minutos.

Fonte

GET direto, sem login, sem proxy, nos ZIPs do TSE em https://cdn.tse.jus.br/estatistica/sead/odsele/:

• candidatos: consulta_cand/consulta_cand_<ano>.zip
• bens: bem_candidato/bem_candidato_<ano>.zip

Dentro de cada ZIP há um CSV por estado, em Latin-1, separado por ;. O Actor não contorna nenhuma proteção.

Como testar

Na pasta deste Actor, com o ambiente virtual criado:

.venv\Scripts\python -m pytest -m "not live"
.venv\Scripts\python -m pytest -m live
.venv\Scripts\python run_local.py '{"ano":2022,"tipo":"candidatos","uf":"AP","limite":5}'

O teste ao vivo baixa os ZIPs de 2022 (cerca de 10 MB).

---

English summary

Brazilian election candidates and declared assets (2018, 2020, 2022, 2024) from the official open data of the TSE (Superior Electoral Court), by state. Returns clean JSON, CSV or Excel rows with stable field names (in Portuguese), filterable by office, party, name, city, elected-only and minimum asset value.

• Input: ano (2018 | 2020 | 2022 | 2024), tipo (candidatos | bens), uf (state code, or BR for president), optional cargo, partido, nome, municipio, apenasEleitos, valorMinimo (assets only), mascararDadosPessoais (default on), limite (default 20, max 10,000).
• Output: one row per candidacy (office, party, ballot name, status, result, birth year, education, occupation) or per declared asset (owner, type, description, value in BRL).
• Pricing (pay per event): US$ 0.002 per run start and US$ 0.001 per record. A default run of 20 records costs US$ 0.022.
• Personal data: CPF (tax id), voter-registration number, full birth date, race/ethnicity, social name and e-mail are not returned; only the birth year is. Plates, RENAVAM and CPF inside free-text asset descriptions are masked by default.
• Limits: each run downloads the full election ZIP (4 to 85 MB) and filters locally. Up to 10,000 records per run. Open data licensed CC-BY; source: TSE. Not affiliated with the TSE. Verify against the source before publishing.