congressapi • congressapi

Set Up

The package congressapi allows you to retrieve data from eleven different Congress API endpoints, returning (most) as data frames by default.

To set up your session, request an API key here. Then use congress_set_key() to save that key to your R session.

library(congressapi)

api_key <- "YOUR_API_KEY_HERE"

congress_set_key(api_key)
#> API Key set: YOUR_API_KEY_HERE

Retrieving Data

You may request data from eleven unique endpoints:

bill
amendment
summaries
congress
member
committee
committee-report
congressional-record
house-communication
nomination
treaty

Here is a basic call to get_congress().

member <- get_congress("member")
member_tbl <- dplyr::tibble(member)

head(member_tbl)
#> # A tibble: 6 × 10
#>   bioguideId name           partyName state terms$item updateDate url   district
#>   <chr>      <chr>          <chr>     <chr> <list>     <chr>      <chr>    <int>
#> 1 F000463    Fischer, Deb   Republic… Nebr… <df>       2023-08-2… http…       NA
#> 2 Q000010    Quie, Albert … Republic… Minn… <df>       2023-08-2… http…        1
#> 3 B001026    Buckley, Jame… Republic… New … <df>       2023-08-1… http…       NA
#> 4 H001052    Harris, Andy   Republic… Mary… <df>       2023-08-0… http…        1
#> 5 B001257    Bilirakis, Gu… Republic… Flor… <df>       2023-08-0… http…       12
#> 6 M001221    Molinaro, Mar… Republic… New … <df>       2023-07-2… http…       19
#> # ℹ 2 more variables: depiction_attribution <chr>, depiction_imageUrl <chr>

Limits and Pagination

By default, the API returns 20 observations per request. To adjust the amount of data returned, you may pass the limit argument to get_congress(). The maximum limit is 250. If greater values are passed, 250 results will be returned.

rows <- 50

bill <- get_congress("bill", limit = rows)

nrow(bill) == rows
#> [1] TRUE

To paginate results, use offset. Because each page returns 20 observations, an offset of 20 will return the second page, 40 will return the third, and so on. Combining this feature with a functional paradigm provides a pleasant method of collating multiple pages into a single data frame.

# Should return 60-row data frame
offsets <- c(20, 40, 60)

three_pages <-
  purrr::map_dfr(
    .x = offsets,
    .f = ~ get_congress("bill",
                       offset = .x)
  )

nrow(three_pages)
#> [1] 60

Note that, because additional arguments like offset and limit are passed via dots, they must be named for the server to understand what their values refer to.

Additional Parameters

In addition to offset and limit, several additional parameters may be passed to the GET request via get_congress(). These include sort (either "asc" or "desc"), fromDateTime, and toDateTime (full timestamps required).

Note that many endpoints, like bill, allow you to explicitly specify a congressional session in the main endpoint path (e.g., "bill/117"). In some cases, this may be preferable to timestamp customization.

Endpoint Paths

Within each endpoint, a variety of more specialized paths may be specified. For instance, to retrieve detailed information on a specific member, you can add a BioGuide ID. Below, note the warning message. Some endpoints cannot be coerced into dataframes and will instead return the content of the API request.

single_member <- get_congress("member/S000033")
#> Warning: endpoint cannot be coerced to dataframe

utils::str(single_member)
#> List of 2
#>  $ member :List of 18
#>   ..$ addressInformation    :List of 5
#>   .. ..$ city         : chr "Washington"
#>   .. ..$ district     : chr "DC"
#>   .. ..$ officeAddress: chr "332 Dirksen Senate Office Building Washington, DC 20510"
#>   .. ..$ phoneNumber  : chr "(202) 224-5141"
#>   .. ..$ zipCode      : int 20515
#>   ..$ bioguideId            : chr "S000033"
#>   ..$ birthYear             : chr "1941"
#>   ..$ cosponsoredLegislation:List of 2
#>   .. ..$ count: int 7170
#>   .. ..$ url  : chr "https://api.congress.gov/v3/member/S000033/cosponsored-legislation"
#>   ..$ currentMember         : logi TRUE
#>   ..$ depiction             :List of 2
#>   .. ..$ attribution: chr "<a href=\"http://www.senate.gov/artandhistory/history/common/generic/Photo_Collection_of_the_Senate_Historical_"| __truncated__
#>   .. ..$ imageUrl   : chr "https://www.congress.gov/img/member/s000033_200.jpg"
#>   ..$ directOrderName       : chr "Bernard Sanders"
#>   ..$ firstName             : chr "Bernard"
#>   ..$ honorificName         : chr "Mr."
#>   ..$ invertedOrderName     : chr "Sanders, Bernard"
#>   ..$ lastName              : chr "Sanders"
#>   ..$ nickName              : chr "Bernie"
#>   ..$ officialWebsiteUrl    : chr "https://www.sanders.senate.gov/"
#>   ..$ partyHistory          :'data.frame':   1 obs. of  3 variables:
#>   .. ..$ partyAbbreviation: chr "I"
#>   .. ..$ partyName        : chr "Independent"
#>   .. ..$ startYear        : int 1991
#>   ..$ sponsoredLegislation  :List of 2
#>   .. ..$ count: int 1063
#>   .. ..$ url  : chr "https://api.congress.gov/v3/member/S000033/sponsored-legislation"
#>   ..$ state                 : chr "Vermont"
#>   ..$ terms                 :'data.frame':   17 obs. of  7 variables:
#>   .. ..$ chamber   : chr [1:17] "House of Representatives" "House of Representatives" "House of Representatives" "House of Representatives" ...
#>   .. ..$ congress  : int [1:17] 102 103 104 105 106 107 108 109 110 111 ...
#>   .. ..$ endYear   : int [1:17] 1993 1995 1997 1999 2001 2003 2005 2007 2009 2011 ...
#>   .. ..$ memberType: chr [1:17] "Representative" "Representative" "Representative" "Representative" ...
#>   .. ..$ startYear : int [1:17] 1991 1993 1995 1997 1999 2001 2003 2005 2007 2009 ...
#>   .. ..$ stateCode : chr [1:17] "VT" "VT" "VT" "VT" ...
#>   .. ..$ stateName : chr [1:17] "Vermont" "Vermont" "Vermont" "Vermont" ...
#>   ..$ updateDate            : chr "2023-04-01T12:42:22Z"
#>  $ request:List of 3
#>   ..$ bioguideId : chr "s000033"
#>   ..$ contentType: chr "application/json"
#>   ..$ format     : chr "json"

To find a complete reference of all valid endpoint paths, visit the Congress API webpage