Retrieve Data from the Census APIs

A wrapper for the U.S. Census Bureau APIs that returns data frames of Census data and metadata. Available datasets include the Decennial Census, American Community Survey, Small Area Health Insurance Estimates, Small Area Income and Poverty Estimates, Population Estimates and Projections, and more.


Build Status CRAN Badge

censusapi is an accessor for the United States Census Bureau's APIs. As of 2017 over 200 Census API endpoints are available, including Decennial Census, American Community Survey, Poverty Statistics, and Population Estimates APIs. This package is designed to let you get data from all of those APIs using the same main function—getCensus—and the same syntax for each dataset.

censusapi generally uses the APIs' original parameter names so that users can easily transition between Census's documentation and examples and this package. It also includes metadata functions to return data frames of available APIs, variables, and geographies.

Installation

Get the latest stable release from CRAN:

install.packages("censusapi")`

You can also install the latest development version of censusapi from Github using devtools. Most people will not want to do this - BEWARE!:

# install.packages("devtools")
devtools::install_github("hrecht/censusapi")

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 use this package. While Census currently does not require an API key for all APIs, that can change at any moment and so this package enforces key usage.

A recommended way to manage your key is to add it to you .Renviron file. Most users will want to do this. Within R, run:

# Add key to .Renviron
Sys.setenv(CENSUS_KEY=YOURKEYHERE)
# Reload .Renviron
readRenviron("~/.Renviron")
# Check to see that the expected key is output in your R console
Sys.getenv("CENSUS_KEY")

Or, open your .Renviron file in a text editor and add the following line: CENSUS_KEY=YOURKEYHERE

Once you've added your census key to your system environment, censusapi will use it by default without any extra work on your part.

In some instances you might not want to put your key in your .Renviron - for example, if you're on a shared school computer. You can always choose to manually set key="YOURKEY" as an argument in getCensus if you prefer.

Usage examples

library(censusapi)

Get uninsured rates from the Small Area Health Insurance Estimates (SAHIE) timeseries API using getCensus().

State-level data by income group within Alabama.

getCensus(name = "timeseries/healthins/sahie",
    vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
    region = "state:1",
    time = 2016)
#>      NAME IPRCAT                IPR_DESC PCTUI_PT time state
#> 1 Alabama      0             All Incomes     11.9 2015    01
#> 2 Alabama      1      <= 200% of Poverty     19.8 2015    01
#> 3 Alabama      2      <= 250% of Poverty     18.6 2015    01
#> 4 Alabama      3      <= 138% of Poverty     21.2 2015    01
#> 5 Alabama      4      <= 400% of Poverty     15.5 2015    01
#> 6 Alabama      5 138% to 400% of Poverty     11.8 2015    01

County-level data within Alabama, specified by adding the regionin parameter.

sahie_counties <- getCensus(name = "timeseries/healthins/sahie",
    vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
    region = "county:*",
    regionin = "state:1",
    time = 2016)
head(sahie_counties, n=12L)
#>                  NAME IPRCAT                IPR_DESC PCTUI_PT time state county
#> 1  Autauga County, AL      0             All Incomes      9.4 2015    01    001
#> 2  Autauga County, AL      1      <= 200% of Poverty     16.8 2015    01    001
#> 3  Autauga County, AL      2      <= 250% of Poverty     15.5 2015    01    001
#> 4  Autauga County, AL      3      <= 138% of Poverty     18.6 2015    01    001
#> 5  Autauga County, AL      4      <= 400% of Poverty     12.4 2015    01    001
#> 6  Autauga County, AL      5 138% to 400% of Poverty      9.6 2015    01    001
#> 7  Baldwin County, AL      0             All Incomes     11.5 2015    01    003
#> 8  Baldwin County, AL      1      <= 200% of Poverty     21.1 2015    01    003
#> 9  Baldwin County, AL      2      <= 250% of Poverty     19.5 2015    01    003
#> 10 Baldwin County, AL      3      <= 138% of Poverty     22.5 2015    01    003
#> 11 Baldwin County, AL      4      <= 400% of Poverty     15.7 2015    01    003
#> 12 Baldwin County, AL      5 138% to 400% of Poverty     12.2 2015    01    003

Retrieve annual data using the time argument by specifying a start year and stop year.

sahie_annual <- getCensus(name = "timeseries/healthins/sahie",
    vars = c("NAME", "PCTUI_PT"),
    region = "state:1",
    time = "from 2006 to 2016")
sahie_annual
#>  time state    NAME PCTUI_PT
#> 1  2006    01 Alabama     15.7
#> 2  2007    01 Alabama     14.6
#> 3  2008    01 Alabama     15.3
#> 4  2009    01 Alabama     15.8
#> 5  2010    01 Alabama     16.9
#> 6  2011    01 Alabama     16.6
#> 7  2012    01 Alabama     15.8
#> 8  2013    01 Alabama     15.9
#> 9  2014    01 Alabama     14.2
#> 10 2015    01 Alabama     11.9
#> 11 2016    01 Alabama     10.8

Read more on how to build a censusapi call in Getting started with censusapi and see examples from every API in the example master list.

Disclaimer

This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

News

censusapi 0.4.1

  • Adds groups type option to listCensusMetadata.
  • Fixes bug in listCensusMetadata variables call caused by an underlying Census API change, which renamed validValues to values for some endpoints.
  • Converts variable metadata columns from factors to characters.
  • Applies numeric conversion exclusions to all API endpoints.
  • Improves language surrounding error messages that the Census Bureau returns.
  • Updates 2010 Decennial Census examples to use new 2010 dec/sf1 endpoint, which will replace 2010 sf1 endpoint on August 30, 2018.

censusapi 0.4.0

censusapi 0.3.0

  • Does not convert ACS annotation flag variables into numeric columns.
  • Puts lowercase variable name columns first (geographies), rather than all non-numeric columns.
  • Changes all punctuation in returned column names into underscores, removing repeated underscores and trailing punctuation.
  • Uses consistent spacing in examples.
  • Updates examples using ACS data to latest year using new acs/acs5 endpoint and adds variable group examples.

censusapi 0.2.1

  • Fixes bug in listCensusMetadata variables call caused by underlying Census API changes.

censusapi 0.2.0

  • Updated examples, documentation, vignette.

censusapi 0.1.2

  • Fixes bug that caused single-row responses to throw an error

censusapi 0.1.1

  • Uses https rather than http for requests. The Census Bureau announced that their APIs will be https-only beginning on August 28, 2017.
  • Removes XML dependency by parsing .json instead of .html metadata.
    • Note: this change has generally increased the run time for retrieving variable metadata with listCensusMetadata. For most APIs, this function will run in under one second. A lag may be noticeable for the American Community Survey APIs, which each have more than 40,000 variables. Improvements are planned in future releases.
  • listCensusMetadata allows full word or single letter argument in type parameter

censusapi 0.1.0.9001

  • Scrapes http://api.census.gov/data.json rather than .html in listCensusApis, in starts of removing XML dependency. The .json data also includes several fields not present in the .html file, the most useful of which are added to the returned data frame.
  • Changes dataset used in listCensusMetadata examples, mainly for build/checks speed.

censusapi 0.1.0.9000

  • Set getCensus(key) argument's default value to be CENSUS_KEY in .Renviron. Explicitly encourages Census key to be added to .Renviron. (Users can always override this with any given input.)
  • Parses HTML response code. This is particularly important for the response that the Census APIs provided for invalid keys.

censusapi 0.1.0

  • Removes fips code 72 (Puerto Rico) from included fips dataset because Puerto Rico is not included in most Census API datasets.
  • Changes census key references in examples to Sys.getenv("CENSUS_KEY").

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("censusapi")

0.6.0 by Hannah Recht, 2 months ago


https://github.com/hrecht/censusapi


Report a bug at https://github.com/hrecht/censusapi/issues


Browse source code at https://github.com/cran/censusapi


Authors: Hannah Recht [aut, cre]


Documentation:   PDF Manual  


Task views: Official Statistics & Survey Methodology


GPL-3 license


Imports httr, jsonlite

Suggests knitr, rmarkdown


See at CRAN