censusapi R Package

The Census Bureau uses "predicates" (filterable parameter variables) to refine queries. You can pass these directly as named arguments to getCensus().

For example, when querying the Small Area Health Insurance Estimates (sahie), you can filter by IPRCAT (income group) and AGECAT (age group) to get highly specific demographic data.

# Get uninsured rate for nonelderly adults (AGECAT = 1)
# at 138% to 400% of the federal poverty line (IPRCAT = 5)
# in Los Angeles County, California
sahie_la <- getCensus(
    name = "timeseries/healthins/sahie",
    vars = c("NAME", "PCTUI_PT"),
    region = "county:037",
    regionin = "state:06",
    time = "from 2012",
    IPRCAT = 5,
    AGECAT = 1)

The U.S. Census Bureau APIs require an API key. censusapi will automatically look for an environment variable named CENSUS_KEY or CENSUS_API_KEY.

To set this up permanently in your R environment, add the key to your .Renviron file. If you are on a shared computer and do not want to save the key to a file, you can pass the key argument directly to getCensus() functions.

# 1. Check if a key is already configured
get_api_key()

# 2. If not, set the environment variable (replace with your actual key)
Sys.setenv(CENSUS_KEY="PASTEYOURKEYHERE")

# 3. Reload the .Renviron file to ensure it is saved
readRenviron("~/.Renviron")

# 4. Verify the key is recognized
get_api_key()

You can install the stable version of censusapi from CRAN or the development version from GitHub using devtools.

# Stable release from CRAN
install.packages("censusapi")

# Development version from GitHub
# install.packages("devtools")
devtools::install_github("hrecht/censusapi")

The primary function for data retrieval is getCensus(). It allows you to fetch data from over 1,500 API endpoints using a consistent syntax.

Common arguments include:

• name: The dataset name (e.g., "acs/acs5/subject" or "timeseries/poverty/saipe").
• vars: A character vector of variable names to retrieve.
• region: The geographic area (e.g., "county:037").
• regionin: The parent geography (e.g., "state:06").
• time: The year or time range (e.g., 2023 or "from 2010").
• vintage: The specific year for datasets that support it.

# Example: Get poverty rate for Los Angeles County, CA from 2010 onwards
poverty_rate <- getCensus(
	name = "timeseries/poverty/saipe",
	vars = c("NAME", "SAEPOVRTALL_PT"),
	region = "county:037",
	regionin = "state:06",
	time = "from 2010")

Before querying data, use listCensusMetadata() to discover available variables, geographic options, and specific values for filterable parameters (predicates).

• Use type = "values" to see the valid codes and labels for a specific variable (e.g., age groups or income categories).

# See the valid codes and labels for the 'IPRCAT' variable
listCensusMetadata(
	name = "timeseries/healthins/sahie",
	type = "values",
	variable = "IPRCAT")