Skip to main content

A python wrapper to fetch votes from BR elections

Project description

Brasilian Elections Python

All Brasilian elections from 1998 to 2018, available on the TSE repository, are accessible by this API. Votes, Candidates, and Parties aggregated by Section, UF, Municipal, and Macro region can be easily filtered through a high-performance Athenas SQL database.

CepespPython is a simple python wrapper designed to assist users in accessing the API to Cepespdata, which facilitates rapid, cleaned, organized and documented access to the Tribunal Superior Eleitoral's data on elections in Brazil from 1998 to 2018.

About the CEPESPdata internal API

This Python project communicates with our CEPESPdata API. All the data within this application was extracted from the official TSE repository. After the extraction, the data files were post-processed and organized using HiveQL and Pandas (Python library). There is also an internal cache to minimize the response time of all pre-made requests.

How to install

The instalation is simple with píp

pip install electionsBR

Core Functionality

After loading the cepesp-R package into your R session, four functions retrieve alternative slices of the processed TSE data. Each returns a data.frame of the requested election details. The following get_* functions don't provide default values for year and position. The four functions are:

  1. get_votes - Details about the number of votes won by each candidate in a specific election. Just specify the position and year of the electoral contest you want data for, and the regional level at which you would like votes to be aggregated. For example, should Presidential election results be returned as national totals for all of Brazil, or separately for each municipality?
get_votes(year=2014, position="President", regional_aggregation="Municipality")
  1. get_candidates - Details about the characteristics of individual candidates competing in an election. Just specify the position and year for which you want data. It's also possible to filter the dataframe to return only the data concerning elected candidates using the option only_elected = TRUE (default option is only_elected = FALSE).
get_candidates(year=2014, position="President")
  1. get_coalitions - Details about the parties that constitute each coalition that competed in each election. Just specify the position and year for which you want data.
get_coalitions(year=2014, position="President")
  1. get_elections - The most comprehensive function which merges data on election results, candidates and coalitions to enable more sophisticated analysis. However, the merges performed here remain imperfect due to errors in the underlying TSE data, and so this function should be treated as beta and used with caution. Specify the position and year for which you want data, the regional aggregation at which votes should be summed, and the political aggregation at which votes should be disaggregated - by individual candidates, parties, coalitions, or as total for each electoral unit. The parameter only-elected is also available for this function (see #2 get_candidates).
get_elections(year=2014, position="President", regional_aggregation="Municipality", political_aggregation="Candidate")
  1. get_assets - Returns the details about assets or goods declared by the candidates in each election. The only mandatory parameter to specify is year. Optional parameters are state and columns_list. For example:
get_assets(year = 2014, state = "AC", columns_list = list('CODIGO_CARGO','NOME_CANDIDATO','CPF_CANDIDATO','VALOR_BEM'))            
  1. get_secretaries - Returns state, state secretary name, date of entry and exit, party affiliation, and other secretaries' personal data. name and state are mandatory arguments to be filled.
get_secretaries(name = 'joao', state = 'AC')
  1. get_filiates - Returns the list of filiates by party and state (status corresponding to the last update in November 2018). state and/or party must be specified as arguments.
get_filiates(state = 'SP', party = 'PT')

Parameters

Check below the available options for each required parameter:

  • year: 1998, 2000, 2002, 2004, 2006, 2008, 2010, 2012, 2014, 2016, 2018.

  • position: Councillor, Mayor, State Deputy, Federal Deputy, Senator, Governor, President.

  • regional_aggregation: Brazil, Macro, State, Meso, Micro, Municipality, Municipality-Zone, Zone, Electoral Section.

  • political_aggregation: Candidate, Party, Coalition, Consolidated.

The same parameters can also be entered in Portuguese:

  • position: Vereador, Prefeito, Deputado Estadual, Deputado Federal, Senador, Governador, Presidente.

  • regional_aggregation: Brasil, Macro, Estado,Meso,Micro, Municipio, Municipio-Zona, Zona, Votação Seção.

  • political_aggregation: Candidato, Partido, Coaligacao, Consolidado.

Deputies for the Federal District (DF) are included in the database as State Deputies and can be obtained through the argument position="State Deputy".

Not all electoral contests occur in every year. Feasible requests are:

Ano Cargos Disponíveis (Descrição)
1998 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual
2000 Prefeito, Vereador
2002 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual
2004 Prefeito, Vereador
2006 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual
2008 Prefeito, Vereador
2010 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual
2012 Prefeito, Vereador
2014 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual
2016 Prefeito, Vereador
2018 Presidente, Governador, Senador, Deputado Federal, Deputado Estadual

It is possible to download multiple years in a single request, once the above-mentioned match of years and positions is observed.

Exemple:

electedmayors_2012_2008 <- get_candidates(year = "2012, 2008", position = "Prefeito", only_elected = T)

Selecting Variables

The default setting is for the function to return all the available variables (columns). To select specific variables and limit the size of the request, you can specify a list of required columns using the columns_list argument. The specific columns available depend on the political and regional aggregation selected, so you are advised to refer to the documentation on the available columns at https://github.com/Cepesp-Fgv/tse-dados/wiki/Colunas and to the API documentation at https://github.com/Cepesp-Fgv/cepesp-rest for further details.

Example:

columns <- list("NUMERO_CANDIDATO","UF","QTDE_VOTOS","COD_MUN_IBGE")

data <- get_votes(year = 2014, position=1, regional_aggregation="Municipality", columns_list=columns)

Filters

To limit the size of the data returned by the API, the request can be filtered to return data on specific units: By state (using the two-letter abbreviation, eg. "RJ"); by party (using the two-digit official party number, eg. 45), or by candidate number.

For example:

data <- get_elections(year = 2014, position=1, regional_aggregation=2, political_aggregation=2, state="RS") #To select Rio Grande do Sul 

data <- get_elections(year = 2014, position=1, regional_aggregation=2, political_aggregation=2, party=13) #To select the PT (=13)

data <- get_elections(year = 2014, position=1, regional_aggregation=2, political_aggregation=2, candidate=2511) #To select candidate 2511

Important: When requesting data with regional_aggregation=9, the filter state should not be NULL

You can see more examples here

Final Note

Remember that all the data returned by the functions above is filtered for apt candidacies (candidacies approved by TSE). Thus, you may find a slightly smaller number of observations in CepespData/FGV datasets than in the original TSE files.

The documentation on the filtering process can be found in this link: https://github.com/Cepesp-Fgv/tse-dados/blob/a28c237bcca0270840a39184e5a98322d3443e60/CepespData/etl/process/VotesVotsecProcess.py#L53.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

electionsBR-0.0.5.tar.gz (9.2 kB view details)

Uploaded Source

Built Distributions

electionsBR-0.0.5-py3.6.egg (16.6 kB view details)

Uploaded Egg

electionsBR-0.0.5-py3-none-any.whl (9.6 kB view details)

Uploaded Python 3

File details

Details for the file electionsBR-0.0.5.tar.gz.

File metadata

  • Download URL: electionsBR-0.0.5.tar.gz
  • Upload date:
  • Size: 9.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.20.1 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.40.2 CPython/3.6.8rc1

File hashes

Hashes for electionsBR-0.0.5.tar.gz
Algorithm Hash digest
SHA256 2f699e8d0d2e6d61b73583a8e97c0d9b28dc3cf439e36aec6828a26b215264a9
MD5 01b7135e17dff749a4c925a154ecb041
BLAKE2b-256 7bd3da68c171f16dbc515a19ed2e6c9c1dcdcaf4b447ca5275117ed30bed826f

See more details on using hashes here.

File details

Details for the file electionsBR-0.0.5-py3.6.egg.

File metadata

  • Download URL: electionsBR-0.0.5-py3.6.egg
  • Upload date:
  • Size: 16.6 kB
  • Tags: Egg
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.20.1 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.40.2 CPython/3.6.8rc1

File hashes

Hashes for electionsBR-0.0.5-py3.6.egg
Algorithm Hash digest
SHA256 df71702f5f66b37f7c9ae203a77eb57bcf1f3316e8a8a1f3b94b07887e7bb3d3
MD5 94f9c217312d324ecb70ea9d9a3e401c
BLAKE2b-256 b60d11ef9ad909fd66dbaa1f32797914b8b0edd940028bfdaf160987327f7a1b

See more details on using hashes here.

File details

Details for the file electionsBR-0.0.5-py3-none-any.whl.

File metadata

  • Download URL: electionsBR-0.0.5-py3-none-any.whl
  • Upload date:
  • Size: 9.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.20.1 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.40.2 CPython/3.6.8rc1

File hashes

Hashes for electionsBR-0.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 74813a296158813c7396b7f586286c779e81cc14c31de9547f4296062b3d6ce8
MD5 7219fc1ba85b116d646dcb6e556caa5e
BLAKE2b-256 ccb87fff7f59fa41ad88100105a45155ceb38cff1ec8682977531fdf80d6fb39

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page