Obtain data and feature geometry for the decennial US Census

get_decennial(
  geography,
  variables = NULL,
  table = NULL,
  cache_table = FALSE,
  year = 2020,
  sumfile = NULL,
  state = NULL,
  county = NULL,
  geometry = FALSE,
  output = "tidy",
  keep_geo_vars = FALSE,
  shift_geo = FALSE,
  summary_var = NULL,
  pop_group = NULL,
  pop_group_label = FALSE,
  key = NULL,
  show_call = FALSE,
  drop_empty = FALSE,
  cb = TRUE,
  labels = FALSE,
  ...
)

Arguments

geography: The geography of your data.
variables: Character string or vector of character strings of variable IDs.
table: The Census table for which you would like to request all variables. Uses Census API groups where supported. Only one table may be requested per call.
cache_table: Deprecated and ignored. Table requests now use Census API groups when supported and do not write to a local cache.
year: The year for which you are requesting data. Defaults to 2020; 2000, 2010, and 2020 are available.
sumfile: The Census summary file; if NULL, defaults to "pl" when the year is 2020 and "sf1" for 2000 and 2010. Not all summary files are available for each decennial Census year. Make sure you are using the correct summary file for your requested variables, as variable IDs may be repeated across summary files and represent different topics.
state: The state 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.
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.
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.
keep_geo_vars: 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.
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 decennial Census to be included in your output. Usually a variable (e.g. total population) that you'll want to use as a denominator or comparison.
pop_group: The population group code for which you'd like to request data. Applies to summary files for which population group breakdowns are available like the Detailed DHC-A file.
pop_group_label: If TRUE, return a "pop_group_label" column that contains the label for the population group. Defaults to FALSE.
key: Your Census API key. Obtain one at https://api.census.gov/data/key_signup.html
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.
drop_empty: 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.
cb: 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.
labels: 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

Value

a tibble or sf tibble of decennial Census data

Examples

if (FALSE) { # \dontrun{
# Plot of race/ethnicity by county in Illinois for 2010
library(tidycensus)
library(tidyverse)
library(viridis)
census_api_key("YOUR KEY GOES HERE")
vars10 <- c("P005003", "P005004", "P005006", "P004003")

il <- get_decennial(geography = "county", variables = vars10, year = 2010,
                    summary_var = "P001001", state = "IL", geometry = TRUE) %>%
  mutate(pct = 100 * (value / summary_value))

ggplot(il, aes(fill = pct, color = pct)) +
  geom_sf() +
  facet_wrap(~variable)


} # }