# Brazil Election Candidates and Assets (TSE): candidatos e bens (`soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens`) Actor Candidatos e bens declarados das eleições de 2018, 2020, 2022 e 2024 (dados abertos do TSE, CC-BY), por estado, cargo, partido ou nome. Sem CPF nem título de eleitor. JSON, CSV ou Excel. - **URL**: https://apify.com/soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens.md - **Developed by:** [Soleene Dados](https://apify.com/soleene) (community) - **Security:** Limited permissions - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## 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): ```json { "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_.zip` - bens: `bem_candidato/bem_candidato_.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: ```powershell .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. # Actor input Schema ## `ano` (type: `string`): 2018 e 2022 são eleições gerais (presidente, governador, senador, deputados). 2020 e 2024 são municipais (prefeito, vice, vereador). Os arquivos de 2020 e 2024 são grandes (de 45 a 85 MB). ## `tipo` (type: `string`): candidatos: um registro por candidatura. bens: um registro por bem declarado, com o nome, cargo e partido de quem declarou. ## `uf` (type: `string`): Sigla do estado. BR traz presidente e vice nas eleições gerais (2018 e 2022). ## `cargo` (type: `string`): Parte do nome do cargo, sem diferenciar acento nem maiúscula. Exemplos: governador, deputado federal, prefeito, vereador. ## `partido` (type: `string`): Sigla do partido como o TSE publica. Exemplos: PT, PL, MDB. ## `nome` (type: `string`): Parte do nome de registro ou do nome de urna. Pelo menos 3 letras. ## `municipio` (type: `string`): Parte do nome do município. Só faz sentido nas eleições municipais (2020 e 2024); nas gerais o campo do TSE é o estado. ## `apenasEleitos` (type: `boolean`): Mantém só quem o TSE marca como eleito (inclui eleito por QP e por média). ## `valorMinimo` (type: `number`): Descarta bens abaixo desse valor. ## `mascararDadosPessoais` (type: `boolean`): Ligado por padrão. A descrição dos bens é texto livre e pode trazer placa e RENAVAM de veículos; esses números e qualquer CPF saem como \*\*\* ou \***.456.789-**. Desligue para manter o texto como a fonte publica. ## `limite` (type: `integer`): Máximo de registros nesta execução. O padrão é pequeno para teste. O teto é 10.000. ## Actor input object example ```json { "ano": "2022", "tipo": "candidatos", "uf": "AP", "apenasEleitos": false, "mascararDadosPessoais": true, "limite": 20 } ``` # Actor output Schema ## `registros` (type: `string`): Um item por candidatura ou por bem. A visão em tabela está no schema do dataset. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,soleene/brazil-election-candidates-and-assets-tse-candidatos-e-bens" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/H2KspVaclT2Nlq1Wc/builds/jFWUMhgfRv6yBap5Q/openapi.json