wru (version 3.0.3)

census_geo_api: Census Data download function.

Description

census_geo_api retrieves U.S. Census geographic data for a given state.

Usage

census_geo_api(
  key = Sys.getenv("CENSUS_API_KEY"),
  state,
  geo = c("tract", "block", "block_group", "county", "place", "zcta"),
  age = FALSE,
  sex = FALSE,
  year = c("2020", "2010"),
  retry = 3,
  save_temp = NULL,
  counties = NULL
)

Value

Output will be an object of class list, indexed by state names. It will consist of the original user-input data with additional columns of Census geographic data.

Arguments

key

A character string containing a valid Census API key, which can be requested from the U.S. Census API key signup page.

By default, attempts to find a census key stored in an environment variable named CENSUS_API_KEY.

state

A required character object specifying which state to extract Census data for, e.g., "NJ".

geo

A character object specifying what aggregation level to use. Use "block", "block_group", "county", "place", "tract", or "zcta". Default is "tract". Warning: extracting block-level data takes very long.

age

A TRUE/FALSE object indicating whether to condition on age or not. If FALSE (default), function will return Pr(Geolocation | Race). If TRUE, function will return Pr(Geolocation, Age | Race). If sex is also TRUE, function will return Pr(Geolocation, Age, Sex | Race).

sex

A TRUE/FALSE object indicating whether to condition on sex or not. If FALSE (default), function will return Pr(Geolocation | Race). If TRUE, function will return Pr(Geolocation, Sex | Race). If age is also TRUE, function will return Pr(Geolocation, Age, Sex | Race).

year

A character object specifying the year of U.S. Census data to be downloaded. Use "2010", or "2020". Default is "2020". Warning: 2020 U.S. Census data is downloaded only when age and sex are both FALSE.

retry

The number of retries at the census website if network interruption occurs.

save_temp

File indicating where to save the temporary outputs. Defaults to NULL. If specified, the function will look for an .RData file with the same format as the expected output.

counties

A vector of counties contained in your data. If NULL, all counties are pulled. Useful for smaller predictions where only a few counties are considered. Must be zero padded.

Details

This function allows users to download U.S. Census geographic data (2010 or 2020), at either the county, tract, block, or place level, for a particular state.

References

Relies on get_census_api(), get_census_api_2(), and vec_to_chunk() functions authored by Nicholas Nagle, available here.

Examples

data(voters)
if (FALSE) census_geo_api(states = c("NJ", "DE"), geo = "block")
if (FALSE) census_geo_api(states = "FL", geo = "tract", age = TRUE, sex = TRUE)
if (FALSE) census_geo_api(states = "MA", geo = "place", age = FALSE, sex = FALSE,
 year = "2020")