{googlecivic} is an R package designed to interface with the Google Civic Information API. In order to use this R package you will need to have a project under a Google Cloud Platform account and will need to create an API key for that project. Log in or create an account for Google Cloud Platform. Click on the dropdown in the console in the top left, then create a new project:
Next, enable APIs and services on the project:
Then, search for the google civic API and enable it:
Create a key for the Google Civic API:
Once you have this API key you can save it somewhere safe and supply it to functions in this R package.
The Google Civic Information API offers several APIs to get information on election information, polling places, and political geographies of representatives. This package current just has a function to interface with the voter information endpoint, but functions will be added in the future to use the full API.
You can install the released version of googlecivic from Github with:
library(remotes)
install_github("willdebras/googlecivic")
The functions for each of the three APIs have a key
argument that
defaults to an object called google_civic_api
. We can use the function
argument to manually include the key, such as:
get_voterinfo(address = "55 e monroe, chicago, il", key =
xxxxxxxxxxxxx)
Alternatively, we can assign the key to an object called
google_civic_api
and leave the key
argument blank, such as:
google_civic_api <- xxxxxxxxxxxxx
The best method to store this key though is probably to set it to an environment variable and call it later, such as:
Sys.setenv(google_civic_api="xxxxxxxxxxxxx")
get_voterinfo(address = "55 e monroe, chicago, il", key = Sys.getenv("google_civic_api"))
You can also use a .Renviron
file to have R automatically set the
environment variable at startup. The package usethis
can be handy for
this.
usethis::edit_r_environ()
This will open a .Renviron file for you. Add a line like this, but substitute your API key:
google_civic_api="xxxxxxxxxxxxx"
Save the file then restart your R session
get_voterinfo(address = "55 e monroe, chicago, il", key = Sys.getenv("google_civic_api"))
The voter information API produces a list of voter information related to a single address or election. The function takes a single argument of a string for an address and returns a nested list of information related to elections, polling locations and information, and state information related to elections.
We can get some basic data about voter information with the
get_voterinfo()
function. Type ?get_voterinfo
to see an explanation
of each parameter.
library(googlecivic)
get_voterinfo(address = "55 e monroe, chicago, il", key = Sys.getenv("google_civic_api"))
#> $error
#> $error$errors
#> domain reason message
#> 1 global invalid Election unknown
#>
#> $error$code
#> [1] 400
#>
#> $error$message
#> [1] "Election unknown"
The election API returns a list of election informations as id, name,
date and Open Civic Data Division Identifier(OCDid). We can get these
data with the get_electionid()
function that receives the API key as
the only argument.
library(googlecivic)
get_electionid(key = Sys.getenv("google_civic_api"))
The representatives by address API retrieves information about
divisions, offices and officials’ information related to an address. The
get_rep_address()
function takes an address, an office level and role
as arguments. For detailed explanation of the each parameter type
?get_rep_voter
.
get_rep_address(address = "55 e monroe, chicago,il", level="regional", role="schoolBoard", key = Sys.getenv("google_civic_api"))
This API returns a list of offices by divisions and respective
officials. The get_rep_by_division()
function takes an OCD identifier
office levels and roles as parameters. The OCDid can be retrieved from
the get_electionid()
function. For detailed explanation about it type
?get_rep_by_division
.
get_rep_by_division(ocdId = "ocd-division/country:us/district:dc",level="locality",recursive = TRUE)
While the {googlecivic} package has documentation in the help files, it can be useful to see an explanation of each endpoint and each parameter in the functions. The Google Civic Information API developer page contains reference to all of these endpoints and parameters and additional documentation of running individual queries outside of the context of this package.
If you have an issue, feature suggestion, or question regarding use, feel free to open an issue here on github or tweet at me @_willdebras.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.