Wrapper for the Project 'VoteSmart' API.

votesmart

This package is a wrapper around the VoteSmartAPI written by your friendly neighborhood progressive tech organization, 🌟 Deck Technologies 🌟. Feel free to use this package in any way you like.

VoteSmart provides information on US political candidates’ positions on issues, votes on bills, and ratings by third party organizations, among other data.

Installation

install.packages("votesmart")

Or the development version:

devtools::install_github("decktools/votesmart", build_vignettes = TRUE)

API Keys

You’ll need a VoteSmart API key in order to use this package. You can register for one here.

Store your key in an environment variable named VOTESMART_API_KEY with

Sys.setenv(VOTESMART_API_KEY = "<your_key>")

You can check that it’s there with

Sys.getenv("VOTESMART_API_KEY")

This package never stores your key in your R session’s global environment.

An Example

VoteSmart collects ratings on various issues that Special Interest Groups (SIGs) give to political candidates.

Let’s say we want to know how Elizabeth Warren tends to be rated on a few issues.

library(votesmart)
suppressPackageStartupMessages(library(dplyr))
conflicted::conflict_prefer("filter", "dplyr")
#> [conflicted] Will prefer dplyr::filter over any other package.

We’ll first want to know what her VoteSmart candidate_id is. We can search for her using candidates_get_by_lastname:

warrens <-
  candidates_get_by_lastname(
    "warren",
    election_years = 2012
  )
#> Requesting data for {last_name: warren, election_year: 2012, stage_id: }.

knitr::kable(warrens)

Filtering to her first name and taking her candidate_id, we can now grab Warren’s ratings by all SIGs with rating_get_candidate_ratings.

(id <-
  warrens %>%
  filter(first_name == "Elizabeth") %>%
  pull(candidate_id)
)
#> [1] "141272"

ratings <-
  rating_get_candidate_ratings(
    candidate_ids = id,
  )
#> Requesting data for {candidate_id: 141272, sig_id: }.

knitr::kable(ratings %>% sample_n(3))

And compute on them:

ratings %>%
  filter(
    category_name_1 %in%
      c(
        "Environment",
        "Fiscally Conservative",
        "Education",
        "Civil Liberties and Civil Rights",
        "Campaign Finance"
      )
  ) %>%
  group_by(category_name_1) %>%
  summarise(
    avg_rating = mean(as.numeric(rating), na.rm = TRUE)
  ) %>%
  arrange(category_name_1)
#> # A tibble: 5 × 2
#>   category_name_1                  avg_rating
#>   <chr>                                 <dbl>
#> 1 Campaign Finance                     100   
#> 2 Civil Liberties and Civil Rights      86.6 
#> 3 Education                             89.3 
#> 4 Environment                           87.2 
#> 5 Fiscally Conservative                  8.78

For more in-depth examples of how these all fit together, check out the vignette with:

vignette("votesmart")

Available Functions

These functions are named after the snake_cased version of the API endpoints.

If you see an endpoint you want to be made available in this package that isn’t yet, feel free to submit an issue or a pull request!

Summary of Functions

candidates_get_by_lastname

Get a dataframe of candidates given a vector of last_names, election_years (optional, defaulting to current year), and stage_ids (optional)

candidates_get_by_levenshtein

Get a dataframe of fuzzy-matched candidates given a vector of last_names, election_years (optional), and stage_ids (optional)

candidates_get_by_office_state

Get a dataframe of candidates by the state in which they ran for office given a vector of state_ids (optional), office_ids, and election_years (optional)

election_get_election_by_year_state

Get a dataframe of election ids and their attributes given a vector of years and state_ids (optional)

measure_get_measures

Get a dataframe of ballot measure attributes given a measure_id

measure_get_measures_by_year_state

Get a dataframe of ballot measure ids and their attributes given a vector of years and state_ids (optional)

office_get_levels

Get the VoteSmart office_level_ids and their associated names (federal, state, local)

office_get_offices_by_level

Get office_ids and their associated names (e.g. "President") for a given office_level_id

rating_get_candidate_ratings

Get SIG (Special Interest Group) ratings for candidates given a candidate_id and a sig_id (optional)

rating_get_categories

Get rating category_ids and their associated names (e.g. "Abortion", "Environment") given a vector of state_ids (optional)

rating_get_sig

Get information about a vector of SIGs (Special Interest Groups) given a sig_id

rating_get_sig_list

Get a dataframe of SIG (Special Interest Group) given a rating category_id and a state_id (optional)

votes_get_by_official

Get a dataframe of the way officials have voted on bills given a candidate_id, an office_id (optional), a category_id (optional) and a year the vote occurred (optional)

Package Data

Only a subset of all of the VoteSmart endpoints have yet been made available through this package.

You can see a full dataframe of the VoteSmart endpoints and their associated arguments with

data("endpoint_input_mapping")

or

data("endpoint_input_mapping_nested")

Other Details

• This package currently contains no rate limiting infrastructure as there is very little information about what rate limits VoteSmart imposes, if any

• The VoteSmart API does not allow for bulk requests, i.e. a single request can only contain one value for each parameter

  • The functions in this package allow multiple inputs to be specified for each argument, but requests are sent one at a time for each combination of inputs

Feel free to reach out in the Issues with any bugs or feature requests! 💫