R package to retrieve Census data and metadata via API
Latest commit a57f626 Nov 30, 2016 @hrecht committed on GitHub verbose package reference
Failed to load latest commit information.
data organize & document Feb 22, 2016
tests add makeVarlist function Feb 29, 2016
test.R use name + vintage everywhere, format listCensusApi response accordingly Feb 28, 2016



Retrieve data from any Census API, as well as metadata about the available datasets and each API's variables and geographies.

For more info and examples, see presentation slides and code from Urban Institute R Users Group presentation, March 2016

API key setup

To use the Census APIs, sign up for an API key, which will be sent to your provided email address. You'll need that key to access the APIs and use this package.


# install.packages("devtools")


There are a few other packages dealing with the Census APIs, but so far they all specialize in only some of the available APIs (e.g. ACS, decennial). This package is dataset agnostic. It also includes functions using the dataset discovery service to return dataset metadata, geographies, and variables as data frames.

Usage examples

# Decennial Census sf3, 1990
data1990 <- getCensus(name="sf3", vintage=1990, key=censuskey, 
    vars=c("P0070001", "P0070002", "P114A001"), 

# 5 year ACS, 2014 - using regionin argument to get data within a state
data2014 <- getCensus(name="acs5", vintage=2014, key=censuskey, 
    vars=c("NAME", "B01001_001E", "B19013_001E", "B17010_017E", "B17010_037E"), 
    region="congressional district:*", regionin="state:36")

# SAHIE time series API, 2011
sahie <- getCensus(name="timeseries/healthins/sahie", key=censuskey, 
    vars=c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT", "RACECAT", "RACE_DESC"), 
    region="state:*", time=2011)

Time series

Time series API arguments vary by API and are still being added to the package and tested. Feel free to submit an issue or pull request if your API isn't yet handled. Note: while the APIs generally return specific error messages for invalid variables or geographies, they currently return no content (status 204) without an error message when an invalid year is specified in some time series. If you're getting repeated 204 responses double check the Census documentation to make sure your time period is valid.