Skip to contents

Fetch ACS table with caching

fetch_acs.Rd

Fetch a table from the American Community Survey (ACS), using cache if available or downloading from Census API. Use for efficient ACS data retrieval in weighting and analysis pipelines.

Usage

fetch_acs(
  table = NULL,
  variables = NULL,
  settings,
  year = NULL,
  acs_dataset = NULL,
  replace = FALSE,
  geography = "block group"
)

Arguments

table

character(1). ACS table name to fetch (e.g., "B01001").

variables

character vector. Variables to fetch. If NULL, fetches all in table.

settings

list. Must include:

  • acs_year — ACS reference year

  • acs_dataset — ACS dataset name

  • inputs_dir — input directory Additional settings as needed for ACS retrieval Modified by reference: no.

year

integer. ACS year. If NULL, uses settings.

acs_dataset

character(1). Dataset: "acs1" or "acs5". If NULL, uses settings.

replace

logical. If TRUE, replaces cached table. Default FALSE.

geography

character(1). Geography level. Default "block group".

Value

data.table. ACS data. Columns:

  • GEOID — block group identifier

  • h_total — total households (if requested)

  • p_total — total persons (if requested)

  • Additional ACS variable columns as requested

Details

  • Loads from cache if file exists and replace = FALSE.

  • Otherwise, fetches from Census API and saves to cache.

  • Handles variable selection, year, dataset, and geography.

  • Returns a copy; does not modify by reference.

  • Assumes valid ACS table, year, and dataset; errors if missing.

Settings

  • acs_year (direct): ACS reference year. Default from settings.

  • acs_dataset (direct): ACS dataset name. Default from settings.

  • inputs_dir (direct): Input directory. Default from settings.

See also

  • get_state_fips, get_county_fips

  • scripts/io/fetch_acs.R

Other io utilities: clean_data_dict(), cut_and_label(), db_table_has_geometry(), fetch_all_hts_tables(), fetch_from_db(), fetch_hts_table(), fetch_pums(), fetch_study_region(), find_project_root(), fix_value_labels_on_load(), get_db_table_name(), print_params(), pums_checksum(), read_from_db(), read_pums_codebook(), record_checksum(), sampled_latlon_to_bg()

Examples

## Not run:
settings <- list(acs_year = 2020, acs_dataset = "acs5", inputs_dir = "inputs")
acs <- fetch_acs(table = "B01001", settings = settings)
#> Fetching ACS data table: B01001
#> Error in get("pops_dir", settings): object 'pops_dir' not found
## End(Not run)