## To cite electionsBR in publications, use: citation('electionsBR')
## To learn more, visit: http://electionsbr.com


electionsBR is an R package used to pull and clean Brazilian electoral data, directly from the Superior Electoral Court (TSE) website. Among others, electionsBR retrieves data on electoral results, candidates’ personal and professional backgrounds, parties’ electoral performances, electoral coalitions, available seats under dispute, and voters’ profile.

How to install

Since the version 0.1.1, electionsBR is on CRAN and can be installed with:


You can install these pre-release versions from GitHub with:

if (!require("devtools")) install.packages("devtools")

How to use

No previous experience with R is required to use the electionsBR package. In fact, it takes only two lines of code to download, clean and export (to Stata and SPSS formats) Brazilian electoral data. For example, here is how we get a full, cleaned dataset with electoral results for the 2010 Federal election:

electionsBR::vote_mun_zone_fed(2010, export = TRUE)

By setting the export argument to TRUE in the vote_mun_zone_fed function, the package will download and clean the relevant data directly from the TSE website and save it in the R working directory (the function automatically tells the user where this directory is located) in two different files:

  1. electoral_data.dta, to be used with Stata;
  2. electoral_data.sav, to be used with SPSS.

Data on elections results

electionsBR‘s chief functions are the ones used to get electoral results, which includes candidates’ number of votes and electoral status (i.e., elected and non-elected), among many others. To get these data, use vote_mun_zone_ functions:

Federal elections results

There are also functions used to quickly access presidential and legislative elections results per state and per municipality – with vote proportions (i.e., vote share) reported. To get presidential runoff (second round) results in runoff, use president_ functions:

To get legislative election results, use instead:


Data on running candidates

Data on candidates’ party affiliation, ballot number, backgrounds and personal information can be retrieved with candidate_ functions:

Data on parties and electoral coalitions

Parties’ electoral performances in both local and federal elections, for all electoral positions, are extracted with:

To get the composition of electoral coalitions (common in proportional elections), use instead:


Data on voters

To get data on voters’ profile in both local and federal elections, use the voter_profile function:

Individual records of partisan affiliation are extracted with the voter_affiliation function:

To consult state abbreviations, use:

##  [1] "AC" "AL" "AM" "AP" "BA" "CE" "DF" "ES" "GO" "MA" "MG" "MS" "MT" "PA"
## [15] "PB" "PE" "PI" "PR" "RJ" "RN" "RO" "RR" "RS" "SC" "SE" "SP" "TO"

A character vector with a list os party abbreviations, valid for 2016 elections, can be obtained with:

##  [1] "PPS"     "PSB"     "PSOL"    "PP"      "PSL"     "PR"      "PSDB"   
##  [8] "PDT"     "PSDC"    "PHS"     "PT"      "PROS"    "PTC"     "PSC"    
## [15] "PC do B" "PRB"     "PMDB"    "DEM"     "PMB"     "PTB"     "PEN"    
## [22] "PTN"     "SD"      "PMN"     "PT do B" "PSD"     "PV"      "PRP"    
## [29] "REDE"    "PPL"     "PRTB"    "PSTU"    "PCB"     "PCO"     "NOVO"

Other functions

electionsBR also includes functions to download data on valid and residual votes and on the number of seats under dispute in each election. The relevant functions are, respectively:


Optional arguments

Exporting Brazilian electoral data

Most electionsBR’s functions accept an export argument (logical, must be TRUE or FALSE; defaults to the latter) controlling whether the functions should export the retrieved data to Stata and SPSS files or not.

df <- party_mun_zone_fed(2010, export = TRUE)

Removing UTF-8 special characters from texts

By default, electionsBR’s functions maintain data’s original encoding (Latin-1) in special characters. To convert strings to ASCII, set the ascii argument to TRUE.

df <- candidate_fed(2010, ascii = TRUE)

In Mac computers, this option may cause errors (or may retrieve incomplete data for the 2016 elections). To avoid them, you may use the encoding optional argument as follows:

df <- candidate_fed(2010, ascii = TRUE, encoding = "Latin-1")

encoding may also be UTF-8 or other valid encodings.

Filtering results by state

Sometimes, getting state electoral data, and not for the whole country, is what one needs. To achieve this, use the uf optional argument (available in most functions):

Notice that the input must be a character vector – with case insensitive state abbreviations (MG, Mg, mG, and mg are all equally valid inputs).

Elections in Brazil

All the data retrieved by electionsBR is made available online by the Brazilian Superior Electoral Court (TSE). As state in the English version of the TSE website, elections in Brazil are organized in the following way:

Are carried out together the federal elections and the state elections, for president and vice president, senator and alternates, governor and vice governor, federal deputies and state deputies. Two years later, will be municipal elections, of mayor and vice mayor and city councils. Note that the distinguishing criterion is by federal level and not by powers – the representatives from the executive and legislative are elected at the same time.

In case of elections for president and vice president, governor and vice governor, senator and alternates and mayor and vice mayor, the system used is the majoritary, in which the most voted candidate will be elected. If none of candidates for president, governor or mayor from a municipality over 200,000 habitants reach the absolute majority of the valid votes, will be convened the second round with the two most voted.

Now for the city council elections and state deputy and federal deputy, the criterion is proportional, which considers not only the candidate votes, but also his party’s votes. Hence, not always the best voted candidate will be elected. The filling of vacancies will depend on the performance of the whole group of candidates of the party or alliance.

Official documentation

electionsBR internal documentation is entirely based on the official documentation provided by the TSE in the Repositorio de Dados Eleitorais.1


The electionsBR package does not modify nor filter the data provided by the TSE – despite its many problems.2 Additionally, users must be aware that the TSE updates its databases frequently, so it is important to register when a version of the electoral data is used. In any case, we are not responsible for problems with the data users may find.

How to cite

To cite electionsBR in publications, please use:

## To cite electionsBR in publications, please use:
##   Meireles, Fernando; Silva, Denisson; Costa, Beatriz. (2016).
##   electionsBR: R functions to download and clean Brazilian
##   electoral data. URL: http://electionsbr.com/
## A BibTeX entry for LaTeX users is
##   @Manual{,
##     title = {{electionsBR}: {R} Functions to Download and Clean {B}razilian Electoral Data},
##     author = {Fernando Meireles and Denisson Silva and Beatriz Costa},
##     year = {2016},
##     url = {http://electionsbr.com/},
##   }

  1. To access the documentation for each type of electoral data, it is necessary to download and open the correspondent compressed files (.zip).

  2. The only exceptions are the president_ and legislative_ functions, which aggregates electoral data in a different unit than in the original files.