candidate_local() downloads and aggregates the data on the candidates' background who vied local elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate.

candidate_local(year, uf = "all", ascii = FALSE, encoding = "latin1",
  export = FALSE)



Election year. For this function, onlye the years of 1996, 2000, 2004, 2008, 2012 and 2016 are available.


Federation Unit acronym (character vector).


(logical). Should the text be transformed from latin1 to ASCII format?


Data original encoding (defaults to 'latin1'). This can be changed to avoid errors when ascii = TRUE.


(logical). Should the downloaded data be saved in .dta and .sav in the current directory?


candidate_local() returns a data.frame with the following variables:

  • DATA_GERACAO: Generation date of the file (when the data was collected).

  • HORA_GERACAO: Generation time of the file (when the data was collected), Brasilia Time.

  • ANO_ELEICAO: Election year.

  • NUM_TURNO: Round number.

  • DESCRICAO_ELEICAO: Description of the election.

  • SIGLA_UF: Units of the Federation's acronym in which occurred the election.

  • SIGLA_UE: Units of the Federation's acronym (In case of major election is the FU's acronym in which the candidate runs for (text) and in case of municipal election is the municipal's Supreme Electoral Court code (number)). Assume the special values BR, ZZ and VT to designate, respectively, Brazil, Overseas and Absentee Ballot.

  • DESCRICAO_UE: Description of the Electoral Unit.

  • CODIGO_CARGO: Code of the position that the candidate runs for.

  • DESCRICAO_CARGO: Description of the position that the candidate runs for.

  • NOME_CANDIDATO: Candidate's complete name.

  • SEQUENCIAL_CANDIDATO: Candidate's sequence number generated internally by the electoral systems. It is not the candidate's campaign number.

  • NUMERO_CANDIDATO: Candidate's number in the ballot box.

  • CPF_CANDIDATO: Candidate's CPF.

  • NOME_URNA_CANDIDATO: Candidate's ballot box name.

  • COD_SITUACAO_CANDIDATURA: Code of the candidature situation.

  • DES_SITUACAO_CANDIDATURA: Description of the candidature situation.

  • NUMERO_PARTIDO: Party number.

  • SIGLA_PARTIDO: Party acronym.

  • NOME_PARTIDO: Party name.

  • CODIGO_LEGENDA: Sequential code of the party shortname generated by the Electoral Justice.

  • SIGLA_LEGENDA: Party's shortname acronym.

  • COMPOSICAO_LEGENDA: Party's shortname composition.

  • NOME_COLIGACAO: Coalition shortname.

  • CODIGO_OCUPACAO: Candidate's occupation code.

  • DESCRICAO_OCUPACAO: Candidate's occupation description.

  • DATA_NASCIMENTO: Candidate's date of birth.

  • NUM_TITULO_ELEITORAL_CANDIDATO: Candidate's ballot number.

  • IDADE_DATA_ELEICAO: Candidate's age on the day of election.

  • CODIGO_SEXO: Candidate's sex code.

  • DESCRICAO_SEXO: Candidate's sex description.

  • COD_GRAU_INSTRUCAO: Candidate's level of education code. Generated internally by the electoral systems.

  • DESCRICAO_GRAU_INSTRUCAO: Candidate's level of education description.

  • CODIGO_ESTADO_CIVIL: Candidate's marital status code.

  • DESCRICAO_ESTADO_CIVIL: Candidate's marital status description.

  • CODIGO_NACIONALIDADE: Candidate's nationality code.

  • DESCRICAO_NACIONALIDADE: Candidate's nationality description.

  • SIGLA_UF_NASCIMENTO: Candidate's Units of the Federation birth's acronym.

  • COD_MUNICIPIO_NASCIMENTO: Candidate's birth city's Supreme Electoral Court code.

  • COD_MUNICIPIO_NASCIMENTO: Candidate's birth city.

  • DESPESA_MAX_CAMPANHA: Maximum expenditure campaign declared by the party to that position. Values in Reais.

  • COD_SIT_TOT_TURNO: Candidate's totalization status code in that election round.

  • DESC_SIT_TOT_TURNO: Candidate's totalization status description in that round.

  • CODIGO_COR_RACA: Candidate's color/race code (self-declaration, only for 2016 election).

  • DESCRICAO_COR_RACA: Candidate's color/race description (self-declaration, only for 2016 election).

  • EMAIL_CANDIDATO: Candidate's e-mail adress (only for 2014 election).


If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.


For the elections prior to 2000, some information can be incomplete.

See also

candidate_fed for federal elections in Brazil.


df <- candidate_local(2000)
# }