Candidatos (consulta_cand)¶
Resumo¶
Cadastro das candidaturas registradas na Justiça Eleitoral a cada eleição, publicado pelo TSE no repositório de dados eleitorais (arquivo consulta_cand). Cada linha é uma candidatura com os dados do registro (cargo, número, nome, partido, federação, coligação), o perfil declarado (idade, gênero, escolaridade, estado civil, cor/raça, ocupação) e a situação de totalização (eleito, suplente, não eleito, 2º turno). Serve para contar candidaturas por cargo, partido, gênero ou escolaridade e como tabela de ligação (sq_candidato) com os bens, a votação e a prestação de contas.
Ficha técnica¶
| Campo | Valor |
|---|---|
| Dataset | tse/candidatos |
| Órgão | Tribunal Superior Eleitoral (TSE) |
| Página oficial | https://dadosabertos.tse.jus.br/dataset/candidatos-2024 |
| Licença | Creative Commons Attribution (CC BY), conforme os conjuntos no portal de dados abertos do TSE: http://www.opendefinition.org/licenses/cc-by. Nenhuma restrição de coleta ou de redistribuição foi encontrada nas páginas dos conjuntos; o LEIAME dos arquivos avisa que CPF, e-mail e outros dados pessoais de candidatos podem vir ocultos (veja os cuidados de uso). |
| Periodicidade | diária segundo o portal de dados abertos (extração com data de geração em cada arquivo) |
| Cobertura | 2018 a 2026 |
| Unidade (uma linha) | uma candidatura (pessoa candidata em uma eleição, cargo, unidade eleitoral e turno) |
| Granularidade | espacial: unidade eleitoral (município, UF ou nacional), com UF; temporal: eleição (ano e turno) |
| Formato bruto | ZIP por ano com um CSV por UF, mais os consolidados BR e BRASIL; CSV em Latin-1 (ISO-8859-1), separador ponto e vírgula, todos os campos entre aspas duplas (inclusive os numéricos), uma linha de cabeçalho |
| Estado no lake | convertido |
| Partições | ano, uf |
| Chave | ano, nr_turno, sq_candidato |
| Colunas | 50 |
| Unidades de medida | — |
| Dados pessoais | nr_cpf_candidato (CPF); nm_candidato (nome); nm_urna_candidato (nome); nm_social_candidato (nome social); ds_email (e-mail (na prática sempre "NÃO DIVULGÁVEL")); dt_nascimento (data de nascimento); nr_titulo_eleitoral_candidato (título de eleitor); sg_uf_nascimento (naturalidade); cd_genero (gênero); ds_genero (gênero); cd_cor_raca (cor/raça (dado sensível)); ds_cor_raca (cor/raça (dado sensível)); cd_estado_civil (estado civil); ds_estado_civil (estado civil); cd_grau_instrucao (escolaridade); ds_grau_instrucao (escolaridade); cd_ocupacao (ocupação); ds_ocupacao (ocupação); sq_candidato (identificador da pessoa candidata) |
| Eras | 2024: cd_situacao_candidatura e ds_situacao_candidatura deixam de ser preenchidas (-3/#NE) e nr_cpf_candidato passa a vir -4 (não divulgável) em todas as linhas; o cabeçalho de 50 colunas não muda de 2018 a 2026 |
| Revisado em | 2026-11-10 |
| Versão do fetcher | 0.3.3 |
Origem e coleta¶
- O fetcher baixa
consulta_cand_<ano>.zipdo CDN de estatísticas eleitorais do TSE (https://cdn.tse.jus.br/estatistica/sead/odsele/consulta_cand/), um ZIP por ano eleitoral. - No bruto o arquivo guarda o nome da fonte, com o manifesto ao lado (
consulta_cand_2024.zipeconsulta_cand_2024.zip.manifest.json). Uma versão nova substitui a anterior. - Dentro do ZIP há
leiame.pdf(o layout oficial, descartado na conversão), um CSV por UF (consulta_cand_<ano>_<UF>.csv, incluindoDF), o consolidadoconsulta_cand_<ano>_BRASIL.csve, nos anos de eleição geral (2018, 2022, 2026),consulta_cand_<ano>_BR.csvcom as candidaturas de abrangência nacional (Presidente e Vice). - Conferido em 2026-11-10 pela listagem do bruto: ZIPs de 2018, 2020, 2022, 2024 e 2026. O fetcher aceita anos desde 1994 (
DEFAULT_YEAR_RANGEé 2018:2026); a fonte publica desde 1933.
Conteúdo¶
- Unidade de análise: a candidatura, identificada por
sq_candidatodentro da eleição (a chave é única porano,nr_turnoesq_candidatonos arquivos por UF conferidos: 1.102.262 linhas distintas em 1.102.262). Osq_candidatoé um sequencial interno de cada eleição, não o número de urna. - Cobertura conferida (arquivo
BRASIL, linhas): 2018: 29.287; 2020: 558.804; 2022: 29.322; 2024: 463.926; 2026: 21.017. As eleições gerais (2018, 2022, 2026) têm de 21 mil a 30 mil candidaturas; as municipais (2020, 2024), meio milhão. - O arquivo de um ano inclui também as eleições suplementares que a fonte atribui àquele ciclo (
cd_tipo_eleicao = 1); em 2024, por exemplo, háds_eleicaode 2021. - Eras: o cabeçalho tem as mesmas 50 colunas em todos os anos conferidos. O que muda é o preenchimento: a partir de 2024 a situação do registro não é mais preenchida e o CPF vem oculto; em 2026 o CPF volta a aparecer nos arquivos conferidos (42.028 de 42.034 linhas com 11 dígitos, contando o
BRASILe as UFs). - Nulos e chave: números conferidos no lake de amostra completo dos cinco anos (2.204.712 linhas, com a duplicação descrita nos cuidados). Só
dt_nascimentotem nulo (940 linhas), exatamente as de candidatos com dados não divulgáveis.
Variáveis¶
Descrições do LEIAME oficial do TSE (consulta_cand, versão de 2024), resumidas; onde o texto não define a variável, a célula diz "não informado pela fonte". Todos os valores chegam ao lake como texto. As colunas de partição ano e uf não fazem parte dos arquivos Parquet e saem do nome do arquivo.
| Coluna no lake | Na fonte | Tipo | Descrição | Unidade / códigos | Período |
|---|---|---|---|---|---|
dt_geracao |
DT_GERACAO |
texto | Data da extração dos dados para geração do arquivo. | — | todo |
hh_geracao |
HH_GERACAO |
texto | Hora da extração dos dados para geração do arquivo com base no horário de Brasília. | — | todo |
ano_eleicao |
ANO_ELEICAO |
texto | Ano de referência da eleição para geração do arquivo. | — | todo |
cd_tipo_eleicao |
CD_TIPO_ELEICAO |
texto | Código do tipo de eleição. | . 1: Eleição Suplementar; . 2: Eleição Ordinária; e . 3: Consulta Popular. | todo |
nm_tipo_eleicao |
NM_TIPO_ELEICAO |
texto | Nome do tipo de eleição. | — | todo |
nr_turno |
NR_TURNO |
texto | Número do turno da eleição. | — | todo |
cd_eleicao |
CD_ELEICAO |
texto | Código único da eleição no âmbito da Justiça Eleitoral. | — | todo |
ds_eleicao |
DS_ELEICAO |
texto | Descrição da eleição. | — | todo |
dt_eleicao |
DT_ELEICAO |
texto | Data da ocorrência da eleição. | — | todo |
tp_abrangencia |
TP_ABRANGENCIA |
texto | Abrangência da eleição. | . M: Municipal; . E: Estadual; e . F: Federal. Observação: a abrangência territorial da eleição está diretamente relacionada aos cargos eletivos e suas circunscrições eleitorais. As eleições (...) | todo |
sg_uf |
SG_UF |
texto | Sigla da unidade da federação na qual a candidata ou candidato concorre na eleição. | — | todo |
sg_ue |
SG_UE |
texto | Sigla da unidade eleitoral na qual a candidata ou candidato concorre na eleição. A unidade eleitoral representa a unidade da federação ou o município em que a candidata ou o candidato concorre na eleição e é relacionada à abrangência territorial desta (...) | — | todo |
nm_ue |
NM_UE |
texto | Nome da unidade eleitoral da candidata ou candidato. Em caso de abrangência nacional, é igual a "Brasil". Em caso de abrangência estadual, é o nome da UF em que a candidata ou candidato concorre. Em caso de abrangência municipal, é o nome do município em que (...) | — | todo |
cd_cargo |
CD_CARGO |
texto | Código do cargo ao qual a candidata ou candidato concorre. | — | todo |
ds_cargo |
DS_CARGO |
texto | Descrição do cargo ao qual a candidata ou candidato concorre. | — | todo |
sq_candidato |
SQ_CANDIDATO |
texto | Número sequencial da candidata ou candidato, gerado internamente pelos sistemas eleitorais para cada eleição. | — | todo |
nr_candidato |
NR_CANDIDATO |
texto | Número da candidata ou candidato na urna. | — | todo |
nm_candidato |
NM_CANDIDATO |
texto | Nome completo da candidata ou candidato. | — | todo |
nm_urna_candidato |
NM_URNA_CANDIDATO |
texto | Nome da candidata ou candidato que aparece na urna. | — | todo |
nm_social_candidato |
NM_SOCIAL_CANDIDATO |
texto | Nome social da candidata ou candidato. | — | todo |
nr_cpf_candidato |
NR_CPF_CANDIDATO |
texto | Número do CPF da pessoa candidata. Não divulgável em 2024 (-4 em todas as linhas conferidas); presente nos arquivos de 2018, 2020, 2022 e 2026 |
CPF de 11 dígitos; -4 = não divulgável |
2018-2022, 2026 |
ds_email |
DS_EMAIL |
texto | Endereço de e-mail da pessoa candidata | conferido: sempre NÃO DIVULGÁVEL |
todo |
cd_situacao_candidatura |
CD_SITUACAO_CANDIDATURA |
texto | Código da situação do registro de candidatura. Segundo a fonte, aplicável só até as eleições de 2022; em 2024 e 2026 vem -3 |
1 cadastrado, 3 inapto, 12 apto (conferido); -3 = não registrado |
até 2022 |
ds_situacao_candidatura |
DS_SITUACAO_CANDIDATURA |
texto | Descrição da situação do registro de candidatura. Segundo a fonte, aplicável só até as eleições de 2022; em 2024 e 2026 vem #NE |
CADASTRADO, INAPTO, APTO; #NE |
até 2022 |
tp_agremiacao |
TP_AGREMIACAO |
texto | Tipo de agremiação da candidatura, ou seja, forma como a candidata ou o candidato concorrerá nas eleições. | . Coligação: quando a candidata ou candidato concorre por coligação; . Federação: quando a candidata ou candidato concorre por uma federação; e . Partido Isolado: quando a candidata ou candidato (...) | todo |
nr_partido |
NR_PARTIDO |
texto | Número do partido da candidata ou candidato. | — | todo |
sg_partido |
SG_PARTIDO |
texto | Sigla do partido da candidata ou candidato. | — | todo |
nm_partido |
NM_PARTIDO |
texto | Nome do partido da candidata ou candidato. | — | todo |
nr_federacao |
NR_FEDERACAO |
texto | Número da federação pela qual o partido da candidata ou candidato concorre na eleição. | — | todo |
nm_federacao |
NM_FEDERACAO |
texto | Nome da federação pela qual o partido da candidata ou candidato concorre na eleição. | — | todo |
sg_federacao |
SG_FEDERACAO |
texto | Sigla da federação pela qual o partido da candidata ou candidato concorre na eleição. | — | todo |
ds_composicao_federacao |
DS_COMPOSICAO_FEDERACAO |
texto | Composição da federação pela qual o partido da candidata ou candidato concorre na eleição. A informação da federação é composta pela concatenação das siglas dos partidos federados intercaladas com o símbolo "/". | — | todo |
sq_coligacao |
SQ_COLIGACAO |
texto | Sequencial da coligação pela qual o partido da candidata ou candidato concorre na eleição. | — | todo |
nm_coligacao |
NM_COLIGACAO |
texto | Nome da coligação pela qual o partido da candidata ou candidato concorre na eleição. | — | todo |
ds_composicao_coligacao |
DS_COMPOSICAO_COLIGACAO |
texto | Composição da coligação pela qual o partido da candidata ou candidato concorre na eleição. A informação da coligação é composta pela concatenação das siglas dos partidos coligados intercaladas com ",". | — | todo |
sg_uf_nascimento |
SG_UF_NASCIMENTO |
texto | Sigla da unidade da federação de nascimento da candidata ou candidato. | — | todo |
dt_nascimento |
DT_NASCIMENTO |
texto | Data de nascimento da candidata ou candidato. | — | todo |
nr_titulo_eleitoral_candidato |
NR_TITULO_ELEITORAL_CANDIDATO |
texto | Número do título eleitoral da candidata ou candidato. | — | todo |
cd_genero |
CD_GENERO |
texto | Código do gênero da candidata ou candidato. | . 2: Masculino; e . 4: Feminino. | todo |
ds_genero |
DS_GENERO |
texto | Descrição do gênero da candidata ou candidato. | — | todo |
cd_grau_instrucao |
CD_GRAU_INSTRUCAO |
texto | Código do grau de instrução da candidata ou candidato. | . 1: Analfabeto; . 2: Lê e escreve; . 3: Ensino fundamental incompleto; . 4: Ensino fundamental completo; . 5: Ensino médio incompleto; . 6: Ensino médio completo; . 7: Superior incompleto; e . 8: (...) | todo |
ds_grau_instrucao |
DS_GRAU_INSTRUCAO |
texto | Descrição do grau de instrução da candidata ou candidato. | — | todo |
cd_estado_civil |
CD_ESTADO_CIVIL |
texto | Código do estado civil da candidata ou candidato. | . 1: Solteiro(a); . 3: Casado(a); . 5: Viúvo(a); . 7: Separado(a) judicialmente; e . 9: Divorciado(a). | todo |
ds_estado_civil |
DS_ESTADO_CIVIL |
texto | Descrição do estado civil da candidata ou candidato. | — | todo |
cd_cor_raca |
CD_COR_RACA |
texto | Código da cor/raça da candidata ou candidato. | . 01: Branca; . 02: Preta; . 03: Parda; . 04: Amarela; . 05: Indígena; e . 06: Não Informado. | todo |
ds_cor_raca |
DS_COR_RACA |
texto | Descrição da cor/raça da candidata ou candidato. | — | todo |
cd_ocupacao |
CD_OCUPACAO |
texto | Código da ocupação da candidata ou candidato. | — | todo |
ds_ocupacao |
DS_OCUPACAO |
texto | Descrição da ocupação da candidata ou candidato. | — | todo |
cd_sit_tot_turno |
CD_SIT_TOT_TURNO |
texto | Código da situação de totalização da candidata ou candidato no turno. | — | todo |
ds_sit_tot_turno |
DS_SIT_TOT_TURNO |
texto | Descrição da situação de totalização da candidata ou candidato no turno. | — | todo |
No lake¶
- Dataset
tse/candidatos, particionado poranoeuf, um Parquet por CSV de origem (por membro do ZIP). anoeufvêm do nome do membro (consulta_cand_2022_SP.csvdáano=2022,uf=sp); oBRvai parauf=bre oBRASILsó é lido se o ZIP não tiver os arquivos por UF (então vai parauf=__HIVE_DEFAULT_PARTITION__).- Todas as colunas são texto, com os nomes da fonte em minúsculas. O CSV é lido em Latin-1 com aspas duplas e campos com quebra de linha tratados. Nenhum marcador vira nulo.
- O LEIAME (
leiame.pdf) é ignorado. O esquema de referência (candidatos.schema.json) tem 50 colunas, gerado de uma conversão real dos cinco anos.
Cuidados de uso¶
- Dupla contagem (corrigida; lake gerado até a versão 0.3.3 ainda tem). O ZIP traz um CSV por UF, o
BR(registros de âmbito nacional, quando existe) e oBRASIL(consolidado que repete as UFs e oBR). O conversor atual não lê oBRASILquando o ZIP tem os arquivos por UF: lê as UFs (uf=<sigla>) e oBR(uf=br, comsg_uf=BR); se o ZIP só tiver oBRASIL, ele é lido e vai parauf=__HIVE_DEFAULT_PARTITION__. Ao descartar oBRASIL, o conversor confere o número de linhas dele com a soma das UFs e doBR; se divergir, registra um aviso com as três contagens e mantém só as UFs e oBR. Assim somar o lake inteiro conta cada linha uma vez. Um lake gerado antes da correção tem os Parquets doBRASILemuf=__HIVE_DEFAULT_PARTITION__e as linhas em dobro: apaguetse/candidatos/e reconverta (veja oCHANGELOG.md). Evidência (conferida em 2026-11-10 com o conversor atual): em 2018 oBRASILtem 29.287 linhas, as UFs somam 29.255 e oBR32, e o lake passa a ter 29.287; em 2020 e 2024 oBRASILtem exatamente a soma das UFs (558.804 e 463.926). - Marcadores da fonte ficam como texto, não viram nulo. Segundo o LEIAME,
#NULOindica campo em branco (-1nos numéricos),#NEindica informação não registrada naquele ano (-3) e-4indica dado pessoal não divulgável. O lake os guarda literais; a escrita varia entre arquivos (#NULO#em 2018 e#NULOem 2024, conferido nas amostras), então teste as duas. Nulo de verdade só aparece em campos vazios. - CPF, título de eleitor e e-mail. O CPF vem preenchido em 2018, 2020, 2022 e 2026 e
-4em 2024; o e-mail é sempreNÃO DIVULGÁVELe o título de eleitor traz o número, salvo-4em candidaturas não divulgáveis. Para candidaturas não divulgáveis o LEIAME diz que os campos textuais pessoais vêm comoNÃO DIVULGÁVEL, os numéricos como-4e a idade e a data de nascimento ficam em branco. Em 2022 há candidaturas comds_genero = NÃO DIVULGÁVEL. - Situação do registro só existe até 2022; para 2024 em diante use
ds_sit_tot_turno, que também traz#NULOpara quem ainda não teve apuração (por exemplo suplementares e candidaturas sem votos). - Eleições suplementares estão no arquivo do ciclo ordinário: filtre por
cd_tipo_eleicao = 2para só a eleição ordinária. - Ano do arquivo e
ano_eleicaocoincidiram nas 2.204.712 linhas conferidas.
Exemplos¶
Candidaturas ordinárias de 2022 por cargo e gênero (cada linha uma vez):
import polars as pl
cand = pl.scan_parquet(
"lake/tse/candidatos/ano=2022/*/*.parquet", hive_partitioning=True
)
resumo = (
cand.filter(pl.col("cd_tipo_eleicao") == "2")
.group_by("ds_cargo", "ds_genero")
.agg(pl.len().alias("candidaturas"))
.sort("ds_cargo", "ds_genero")
.collect()
)
Referências¶
- Conjunto de 2024: https://dadosabertos.tse.jus.br/dataset/candidatos-2024 (há um por ano,
candidatos-<ano>) - Repositório de dados eleitorais (CDN): https://cdn.tse.jus.br/estatistica/sead/odsele/consulta_cand/
- Layout:
leiame.pdfdentro de cada ZIP - Contato da fonte para dúvidas: [email protected] (citado no LEIAME)