Skip to contents

Get multiple tables or multiple geographies of ACS data

Source: R/get_acs_ext.R
get_acs_tables.Rd

[Experimental] These functions wrap tidycensus::get_acs() and label_acs_metadata() to support downloading multiple tables and combining tables into a single data frame or downloading data for multiple geographies. Note that while the Census API does not have a specific rate or request limit when using a Census API key, using these functions with a large number of tables or geographies may result in errors or failed requests.

CRAN policies require that tidycensus avoid caching by default, however, this package sets cache_table = TRUE by default to avoid unecessary load on the Census API.

Usage

get_acs_tables(
  geography,
  table = NULL,
  cache_table = TRUE,
  year = 2021,
  survey = "acs5",
  ...,
  crs = NULL,
  label = TRUE,
  perc = TRUE,
  keep_geography = TRUE,
  geoid_col = "GEOID",
  quiet = FALSE,
  call = caller_env()
)

get_acs_geographies(
  geography = c("county", "state"),
  variables = NULL,
  table = NULL,
  cache_table = TRUE,
  year = 2021,
  state = NULL,
  county = NULL,
  msa = NULL,
  survey = "acs5",
  ...,
  label = TRUE,
  perc = TRUE,
  geoid_col = "GEOID",
  quiet = FALSE
)

get_acs_geography(
  geography,
  variables = NULL,
  table = NULL,
  cache_table = TRUE,
  year = 2021,
  state = NULL,
  county = NULL,
  msa = NULL,
  survey = "acs5",
  ...,
  label = TRUE,
  perc = TRUE,
  geoid_col = "GEOID",
  call = caller_env()
)

Arguments

geography

Required character vector of one or more geographies. See https://walker-data.com/tidycensus/articles/basic-usage.html#geography-in-tidycensus for supported options. Defaults to c("county", "state") for get_acs_geographies(). If a supplied geography does not support county and state parameters, these options are dropped before calling tidycensus::get_acs(). Any required parameters are also bound to the returned data frame as new columns.

table

A character vector of tables.

cache_table

Whether or not to cache table names for faster future access. Defaults to FALSE; if TRUE, only needs to be called once per dataset. If variables dataset is already cached via the load_variables function, this can be bypassed.

year

The year, or endyear, of the ACS sample. 5-year ACS data is available from 2009 through 2021; 1-year ACS data is available from 2005 through 2021, with the exception of 2020. Defaults to 2021.

survey

The ACS contains one-year, three-year, and five-year surveys expressed as "acs1", "acs3", and "acs5". The default selection is "acs5."

...

Arguments passed on to tidycensus::get_acs

output

One of "tidy" (the default) in which each row represents an enumeration unit-variable combination, or "wide" in which each row represents an enumeration unit and the variables are in the columns.

zcta

The zip code tabulation area(s) for which you are requesting data. Specify a single value or a vector of values to get data for more than one ZCTA. Numeric or character ZCTA GEOIDs are accepted. When specifying ZCTAs, geography must be set to `"zcta"` and `state` must be specified with `county` left as `NULL`. Defaults to NULL.

geometry

if FALSE (the default), return a regular tibble of ACS data. if TRUE, uses the tigris package to return an sf tibble with simple feature geometry in the `geometry` column.

keep_geo_vars

if TRUE, keeps all the variables from the Census shapefile obtained by tigris. Defaults to FALSE.

shift_geo

(deprecated) if TRUE, returns geometry with Alaska and Hawaii shifted for thematic mapping of the entire US. Geometry was originally obtained from the albersusa R package. As of May 2021, we recommend using tigris::shift_geometry() instead.

summary_var

Character string of a "summary variable" from the ACS to be included in your output. Usually a variable (e.g. total population) that you'll want to use as a denominator or comparison.

key

Your Census API key. Obtain one at https://api.census.gov/data/key_signup.html

moe_level

The confidence level of the returned margin of error. One of 90 (the default), 95, or 99.

show_call

if TRUE, display call made to Census API. This can be very useful in debugging and determining if error messages returned are due to tidycensus or the Census API. Copy to the API call into a browser and see what is returned by the API directly. Defaults to FALSE.

crs

Coordinate reference system to use for returned sf tibble when geometry = TRUE is passed to tidycensus::get_acs(). Defaults to NULL.

label

If TRUE (default), label the returned ACS data with label_acs_metadata() before returning the data frame.

perc

If TRUE (default), use the denominator column ID to calculate each estimate as a percent share of the denominator value and use tidycensus::moe_prop() to calculate a new margin of error for the percent estimate.

keep_geography

If TRUE (default), bind geography and any supplied county or state columns to the returned data frame.

geoid_col

A GeoID column name to use if perc is TRUE, Defaults to 'GEOID'.

quiet

If FALSE (default), leave cli.default_handler option unchanged. If TRUE, set cli.default_handler to suppressMessages temporarily with rlang::local_options()

call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

variables

Character string or vector of character strings of variable IDs. tidycensus automatically returns the estimate and the margin of error associated with the variable.

state

An optional vector of states for which you are requesting data. State names, postal codes, and FIPS codes are accepted. Defaults to NULL.

county

The county for which you are requesting data. County names and FIPS codes are accepted. Must be combined with a value supplied to `state`. Defaults to NULL.

msa

Name or GeoID of a metro area that should be filtered from the overall list of metro areas returned when geography or geographies is "metropolitan/micropolitan statistical area", "cbsa", or "metropolitan statistical area/micropolitan statistical area".

Examples

if (FALSE) {
if (interactive()) {
  get_acs_tables(
    geography = "county",
    county = "Baltimore city",
    state = "MD",
    table = c("B01003", "B19013")
  )

  get_acs_geographies(
    geography = c("county", "state"),
    state = "MD",
    table = c("B01003", "B19013")
  )
}
}