Obtain data and feature geometry for the American Community Survey
get_acs(
geography,
variables = NULL,
table = NULL,
cache_table = FALSE,
year = 2024,
output = "tidy",
state = NULL,
county = NULL,
zcta = NULL,
geometry = FALSE,
keep_geo_vars = FALSE,
shift_geo = FALSE,
summary_var = NULL,
key = NULL,
moe_level = 90,
survey = "acs5",
show_call = FALSE,
drop_empty = FALSE,
cb = TRUE,
suffix = c("E", "M"),
labels = FALSE,
...
)The geography of your data.
Character string or vector of character strings of variable IDs. tidycensus automatically returns the estimate and the margin of error associated with the variable.
The ACS table for which you would like to request all variables. Uses Census API groups where supported. Only one table may be requested per call.
Deprecated and ignored. Table requests now use Census API groups and do not write to a local cache.
The year, or endyear, of the ACS sample. 5-year ACS data is available from 2009 through 2023; 1-year ACS data is available from 2005 through 2023, with the exception of 2020. Defaults to 2023.
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.
An optional vector of states for which you are requesting data. State names, postal codes, and FIPS codes are accepted. Defaults to NULL.
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.
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 `county` left as `NULL`. `state` can be used to request ZCTAs within a state for the 2011-2019 ACS only; the Census API does not support this for 2020 and later. Defaults to NULL.
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.
if TRUE, keeps all the variables from the Census
shapefile obtained by tigris. Defaults to FALSE. As the shapefile has its own NAME column, the
shapefile's name is returned as NAME.x and the Census name for each geography
(the NAME column when keep_geo_vars = FALSE) as NAME.y.
(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.
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.
Your Census API key. Obtain one at https://api.census.gov/data/key_signup.html
The confidence level of the returned margin of error. One of 90 (the default), 95, or 99.
The ACS contains one-year, three-year, and five-year surveys expressed as "acs1", "acs3", and "acs5". The default selection is "acs5."
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.
if TRUE and geometry = TRUE, drops rows with empty geometries.
These are typically water-only areas, such as offshore block groups,
that are not in the cartographic boundary files used by default; use
cb = FALSE to return TIGER/Line geometries for these areas instead.
Defaults to FALSE.
if TRUE (the default), uses the Census Bureau's cartographic boundary files
for feature geometry when geometry = TRUE. These are generalized and clipped to
the shoreline. If FALSE, uses the more detailed TIGER/Line files, which include water
area. Note that tigris functions default to cb = FALSE. TIGER/Line files are
always used for 2011 and 2012, when cartographic boundary files are not available.
A character vector of two suffixes for the estimate and margin of
error columns when output = "wide". Defaults to c("E", "M"), giving
columns like B19013_001E and B19013_001M; for example,
c("_est", "_moe") gives B19013_001_est and B19013_001_moe.
Ignored when output = "tidy".
Name variables from their labels instead of their IDs.
FALSE (the default) uses variable IDs. TRUE uses cleaned labels
(e.g. total_male_under_5_years), in the variable column of tidy
output or the column names of wide output; variables whose labels are identical
get their concept added (e.g. total_male_under_5_years_white_alone).
"concept" always adds the concept to the name. "attributes" keeps
the IDs and attaches the cleaned label (e.g. "Total > Male > Under 5 years") and
concept to each column of wide output as label and concept
attributes; it has no effect on tidy output. Variables you name yourself in
variables keep your names.
Other keyword arguments
A tibble or sf tibble of ACS data
if (FALSE) { # \dontrun{
library(tidycensus)
library(tidyverse)
library(viridis)
census_api_key("YOUR KEY GOES HERE")
tarr <- get_acs(geography = "tract", variables = "B19013_001",
state = "TX", county = "Tarrant", geometry = TRUE, year = 2020)
ggplot(tarr, aes(fill = estimate, color = estimate)) +
geom_sf() +
coord_sf(crs = 26914) +
scale_fill_viridis(option = "magma") +
scale_color_viridis(option = "magma")
vt <- get_acs(geography = "county", variables = "B19013_001", state = "VT", year = 2019)
vt %>%
mutate(NAME = gsub(" County, Vermont", "", NAME)) %>%
ggplot(aes(x = estimate, y = reorder(NAME, estimate))) +
geom_errorbar(aes(xmin = estimate - moe, xmax = estimate + moe), width = 0.3, size = 0.5) +
geom_point(color = "red", size = 3) +
labs(title = "Household income by county in Vermont",
subtitle = "2015-2019 American Community Survey",
y = "",
x = "ACS estimate (bars represent margin of error)")
} # }