Label ZIP Codes with Contextual Data

This function appends information about the city (for five-digit ZIP Codes) or area (for three-digit ZIP Codes) to a data frame containing these values. State is returned for both types of ZIP Codes. The function also optionally returns data on Sectional Center Facilities (SCFs) for three-digit ZIP Codes.

Usage

zi_label(.data, input_var, label_source = "UDS", source_var,
    type = "zip5", include_scf = FALSE, vintage = 2022)

Arguments

.data: An "input object" that is data.frame or tibble that contains ZIP Codes to be crosswalked.
input_var: The column in the input data that contains five-digit ZIP Codes. If the input is numeric, it will be transformed to character data and leading zeros will be added.
label_source: Required character scalar or data frame; specifies the source of the label data. This could be either 'UDS' (default) or 'USPS', or a data frame containing a custom dictionary.
source_var: Character scalar, required when label_source is a data frame containing a custom dictionary; specifies the column name in the dictionary object that contains ZIP Codes.
type: Character scalar, required when label_source is either label_source is 'UDS' or 'USPS'; one of either 'zip3' or 'zip5'. The 'zip3' type is only available from the 'USPS' source, while the 'zip5' type is available from 'UDS'.
include_scf: A logical scalar required when label_source = 'USPS' and type = 'zip3'; specifying whether to include the SCF (Sectional Center Facility) ID in the output. The default is FALSE.
vintage: Character or numeric scalar, required when label_source is either label_source is 'UDS' or 'USPS'; specifying the date for label_source = 'USPS' or the year of the data for label_source = 'UDS'. The zip_load_labels_list() function can be used to see available date values for label_source = 'USPS'.

Value

A tibble containing the original data with additional columns from the selected label data set appended.

Details

Labels are approximations of the actual location of a ZIP Code. For five-digit ZIP Codes, the city and state may or may not correspond to an individuals' mailing address city (since multiple cities may be accepted as valid by USPS for a particular ZIP Code) or state (since ZIP Codes may cross state lines).

For three-digit ZIP Codes, the area and state may or may not correspond to an individuals' mailing address state (since SCFs cover multiple states). For example, the three digit ZIP Code 010 covers Western Massachusetts in practice, but is assigned to the state of Connecticut.

Examples

# create sample data
df <- data.frame(
  id = c(1:3),
  zip5 = c("63005", "63139", "63636"),
  zip3 = c("630", "631", "636")
)

# UDS crosswalk
# \donttest{
  zi_label(df, input_var = zip5, label_source = "UDS", vintage = 2022)
#> # A tibble: 3 × 6
#>   zip5     id zip3  label_city   label_state label_type   
#>   <chr> <int> <chr> <chr>        <chr>       <chr>        
#> 1 63005     1 630   Chesterfield MO          Zip Code Area
#> 2 63139     2 631   Saint Louis  MO          Zip Code Area
#> 3 63636     3 636   Des Arc      MO          Zip Code Area
# }

# USPS crosswalk
# \donttest{
  zi_label(df, input_var = zip3, label_source = "USPS", type = "zip3",
    vintage = 202408)
#> # A tibble: 3 × 5
#>   zip3     id zip5  label_area label_state
#>   <chr> <int> <chr> <chr>      <chr>      
#> 1 630       1 63005 ST LOUIS   MO         
#> 2 631       2 63139 ST LOUIS   MO         
#> 3 636       3 63636 ST LOUIS   MO         
# }

# custom dictionary
## load sample ZIP3 label data to simulate custom dictionary
mo_label <- zi_mo_usps

## label
zi_label(df, input_var = zip3, label_source = mo_label, source_var = zip3,
  type = "zip3")
#> # A tibble: 3 × 5
#>   zip3     id zip5  label_area label_state
#>   <chr> <int> <chr> <chr>      <chr>      
#> 1 630       1 63005 ST LOUIS   MO         
#> 2 631       2 63139 ST LOUIS   MO         
#> 3 636       3 63636 ST LOUIS   MO