zipcodeR

R-CMD-check · Codecov · CRAN release · CRAN downloads

Makes dealing with U.S. ZIP codes painless.

{zipcodeR} is an R package that makes working with ZIP codes in R easier. It provides data on all U.S. ZIP codes using multiple open data sources, making it easier for social science researchers and data scientists to work with ZIP code-level data in data science projects using R.

The latest update to {zipcodeR} includes new functions for searching ZIP codes at various geographic levels & geocoding.

Installation

You can install the released version of zipcodeR from CRAN with:

install.packages("zipcodeR")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("gavinrozzi/zipcodeR")

Reproducibility and data vintages

For new analyses, the recommended interface is the _ng API with a named, checksum-verified modern data bundle. The suffix is a deliberate signal that the caller has chosen the newer data and corrected behavior. A project still pins one exact bundle version; _ng never means “automatically use whatever is newest.”

Version 0.4.0 also keeps every existing function and all three bundled datasets identical to 0.3.5. Existing calls therefore keep their historical results, including known edge-case behavior:

zip_distance("08731", "08901")
#>   zipcode_a zipcode_b distance
#> 1     08731     08901     40.7
get_cd("08731")
#> $state_fips
#> [1] "NJ"
#>
#> $district
#> [1] "03"
zip_data_version()
#> $data_version
#> [1] "legacy-0.3.5"
#>
#> $package_version
#> [1] "0.3.5"
#>
#> $zip_code_db_rows
#> [1] 41877
#>
#> $zcta_crosswalk_rows
#> [1] 148897
#>
#> $zip_to_cd_rows
#> [1] 45914
#>
#> $sources
#> $sources$zip_code_db
#> [1] "uszipcode-project 0.2.6-db-file (2021-06-08)"
#>
#> $sources$zcta_crosswalk
#> [1] "U.S. Census 2010 ZCTA-to-tract relationship file"
#>
#> $sources$zip_to_cd
#> [1] "pre-2020 HUD-USPS congressional-district crosswalk"
#>
#>
#> $compatibility_contract
#> [1] "Exact zipcodeR 0.3.5 defaults"

Start a new project by downloading the exact registered bundle version, or reading a checksum-pinned file for an offline workflow, then pass the bundle explicitly to _ng functions:

bundle <- download_zip_data_bundle("2026.09")
# Offline alternative:
# bundle <- read_zip_data_bundle(
#   "zipcodeR-data-2026.09.rds",
#   sha256 = "SHA256_FROM_THE_RELEASE_MANIFEST"
# )

zip_distance_ng(bundle, "08731", "08901")
get_cd_ng(bundle, "08731")
zip_data_version(bundle)

No lookup downloads data, selects a latest version, or changes a global option. Record zip_data_version(bundle) and its bundle_sha256 field with research outputs. See the “Legacy and next-generation data” vignette.

Citing {zipcodeR} in Publications

If you use {zipcodeR} in a publication, please cite the following journal article.

A BibTeX entry for LaTeX users is:

@article{ROZZI2021100099,
title = {zipcodeR: Advancing the analysis of spatial data at the ZIP code level in R},
journal = {Software Impacts},
volume = {9},
pages = {100099},
year = {2021},
issn = {2665-9638},
doi = {https://doi.org/10.1016/j.simpa.2021.100099},
url = {https://www.sciencedirect.com/science/article/pii/S2665963821000373},
author = {Gavin C. Rozzi},
keywords = {ZIP code, R, ZCTA, ZIP code tabulation area, zipcodeR},
abstract = {The United States Postal Service (USPS) assigns unique identifiers for postal service areas known as ZIP codes which are commonly used to identify cities and regions throughout the United States in datasets. Despite the widespread use of ZIP codes, there are challenges in using them for geospatial analysis in the social sciences. This paper presents zipcodeR, an R package that facilitates analysis of ZIP code-level data by providing an offline database of ZIP codes and functions for geocoding, normalizing and retrieving data about ZIP codes and relating them to other geographies in R without depending on any external services.}
}

Recommended workflow for new analyses

library(zipcodeR)
bundle <- download_zip_data_bundle("2026.09")

search_state_ng(bundle, "NJ")
zip_distance_ng(bundle, "08901", "08731")
geocode_zip_ng(bundle, "08901")
reverse_zipcode_ng(bundle, "08901")
search_county_ng(bundle, "Ocean", "NJ")
search_city_ng(bundle, "Jersey City", "NJ")
search_tz_ng(bundle, "Eastern")
get_tracts_ng(bundle, "08731")

# Save this beside the analysis outputs.
saveRDS(zip_data_version(bundle), "zipcodeR-data-version.rds")

For existing scripts, keep using the unsuffixed functions. They intentionally continue to use the historical 0.3.5 data and behavior, so upgrading zipcodeR does not rewrite a prior result. New code should use _ng only after choosing and recording the modern bundle version it intends to analyze.

Documentation

Documentation for the current release is available here. See the reference section for full details on how to use each of the functions provided by zipcodeR.

Data Sources

This project was inspired by the excellent uszipcode library for Python and utilizes the same backend database released by its author under the MIT license. This project also incorporates open data from the U.S. Census Bureau and Department of Housing & Urban Development.