Skip to contents

Load Crosswalk Files

Source: R/zi_load_crosswalk.R
zi_load_crosswalk.Rd

Spatial data on USPS ZIP Codes are not published by the U.S. Postal Service or the U.S. Census Bureau. Instead, ZIP Codes can be converted to a variety of Census Bureau geographies using crosswalk files. This function reads in ZIP Code to ZIP Code Tabulation Area (ZCTA) crosswalk files from the former UDS Mapper project, which was sunset by the American Academy of Family Physicians in early 2024. It also provides access to the U.S. Department of Housing and Urban Development's ZIP Code crosswalk files, which provide similar functionality for converting ZIP Codes to a variety of geographies including counties.

Usage

zi_load_crosswalk(
  zip_source = "UDS",
  year,
  qtr = NULL,
  target = NULL,
  query = NULL,
  key = NULL
)

Arguments

zip_source

Required character scalar; specifies the source of ZIP Code crosswalk data. This can be one of either "UDS" (default) or "HUD".

year

Required four-digit numeric scalar for year; varies based on source. For "UDS", years 2009 through 2022 are available. For "HUD", years 2010 through 2024 are available.

qtr

Numeric scalar, required when zip_code is "HUD". Integer value between 1 and 4, representing the quarter of the year.

target

Character scalar, required when zip_code is "HUD". Can be one of "TRACT", "COUNTY", "CBSA", "CBSADIV", "CD", and "COUNTYSUB".

query

Scalar or vector, required when zip_code is "HUD". This can be a five-digit numeric or character ZIP Code, a vector of ZIP Codes, a two-letter character state abbreviation, or "all".

key

Optional when zip_code is "HUD". This should be a character string containing your HUD API key. Alternatively, it can be stored in your .RProfile as hud_key.

Value

A tibble containing the crosswalk file.

Examples

if (FALSE) { # interactive()
 # former UDS mapper crosswalks
 zi_load_crosswalk(zip_source = "UDS", year = 2020)
}
if (FALSE) { # nzchar(Sys.getenv("hud_key"))
 # HUD crosswalks
 ## ZIP Code to CBSA crosswalk for all ZIP Codes
 zi_load_crosswalk(zip_source = "HUD", year = 2023, qtr = 1, target = "CBSA",
     query = "all", key = Sys.getenv("hud_key"))

 ## ZIP Code to County crosswalk for all ZIP Codes in Missouri
 zi_load_crosswalk(zip_source = "HUD", year = 2023, qtr = 1, target = "COUNTY",
     query = "MO", key = Sys.getenv("hud_key"))

 ## ZIP Code to Tract crosswalk for ZIP Code 63139 in St. Louis City
 zi_load_crosswalk(zip_source = "HUD", year = 2023, qtr = 1, target = "TRACT",
     query = 63139, key = Sys.getenv("hud_key"))
}