Setup

If you have not done so already, create an account here. Creating an account is free, and you will be granted 1000 free credits (1 credit per query). Further use will require the purchase of additional credits.

You need three items to query the API: (1) a key; (2) a user id; and (3) a token. You can find your key in your account profile but must make a POST request to obtain your user id and token.

Once you obtain your key, run:

library(rcicero)
set_token_and_user("your_account_email_address", "your_password")
## [1] "Your Cicero API user and token options have been set."

Behind the scenes, rcicero stashes the user and token values into your global options. You must then add the key to your .Renviron, as "CICERO_API_KEY". For help on setting up your .Renviron (and everything else R-related) see Jenny Bryan’s Stat545 page. Warning: the API token expires every 24 hours.

Usage

Four functions make the bulk of rcicero: get_legislative_district(), get_nonlegislative_district(), get_upcoming_elections(), and get_official(). The first three return a data_frame, while get_official() returns a list of four data frames. Why? I thought it was easier and cleaner than coercing all the information into a single table.

Here’s a call to get_legislative_district():

library(dplyr)
ld <- get_legislative_district("3175 Bowers Ave. Santa Clara, CA")
## [1] "You have 871 credits remaining."
ld %>% 
  filter(district_type == "STATE_LOWER") %>% 
  select(-address) %>% 
  knitr::kable()
latitude longitude district_type state district_id label
37.37856 -121.976561 STATE_LOWER CA 25 California Assembly district 25

Other district_types include "STATE_LOWER", "STATE_UPPER", "NATIONAL_LOWER", "NATIONAL_UPPER", and "NATIONAL_EXEC".

Here’s a call to get_nonlegislative_district():

nld <- get_nonlegislative_district("3175 Bowers Ave. Santa Clara, CA", type = "SCHOOL")
## [1] "You have 870 credits remaining."
nld %>% 
  select(-address) %>% 
  knitr::kable()
latitude longitude district_type label subtype state
37.37856 -121.976561 SCHOOL Santa Clara Unified School District UNIFIED CA

Other types include "CENSUS", "COUNTY", "JUDICIAL", "POLICE", and "WATERSHED".

Here’s a call to get_upcoming_elections():

upcoming_elections <- get_upcoming_elections(is_state = TRUE, elections = 6)
## [1] "You have 870 credits remaining."
names(upcoming_elections)
##  [1] "election_label"     "election_date"      "id"                
##  [4] "term_length"        "chamber_type"       "name_formal"       
##  [7] "election_frequency" "contact_email"      "contact_phone"     
## [10] "election_rules"     "state"              "full_name"         
## [13] "name_short"         "name_long"
head(upcoming_elections)
## # A tibble: 6 x 14
##                         election_label     election_date    id term_length
##                                  <chr>             <chr> <chr>       <chr>
## 1       Michigan House Special Primary    30 August 2016  2463     2 years
## 2 Mecklenburg-Vorpommern State Landtag  4 September 2016   877     4 years
## 3        Hong Kong Legislative Council  4 September 2016   705            
## 4        Alabama House Special Primary 13 September 2016  2443     4 years
## 5      Berlin House of Representatives 18 September 2016   931            
## 6             Russia Parliament (Duma) 18 September 2016  2265     4 years
## # ... with 10 more variables: chamber_type <chr>, name_formal <chr>,
## #   election_frequency <chr>, contact_email <chr>, contact_phone <chr>,
## #   election_rules <chr>, state <chr>, full_name <chr>, name_short <chr>,
## #   name_long <chr>

Here’s a call to get_official():

jl <- get_official(first_name = "John", last_name = "Lewis")
## [1] "You have 869 credits remaining."
class(jl)
## [1] "list"
lapply(jl, dim)
## $get_info_and_identifiers
## [1]  9 10
## 
## $committee_info
## [1] 1 4
## 
## $address_info
## [1]  4 10
## 
## $district_info
## [1] 1 8
lapply(jl, names)
## $get_info_and_identifiers
##  [1] "last_name"               "first_name"             
##  [3] "notes"                   "photo_url"              
##  [5] "party"                   "initial_start_date"     
##  [7] "current_term_start_date" "webform_url"            
##  [9] "identifier"              "identifier_type"        
## 
## $committee_info
## [1] "last_name"   "first_name"  "description" "comm_id"    
## 
## $address_info
##  [1] "last_name"   "first_name"  "postal_code" "phone"       "fax"        
##  [6] "city"        "state"       "address_1"   "address_2"   "address_3"  
## 
## $district_info
## [1] "last_name"     "first_name"    "district_type" "country"      
## [5] "district_id"   "label"         "state"         "subtype"