Legacy and next-generation data
In zipcodeR: Data & Functions for Working with US ZIP Codes

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(zipcodeR)

Which interface should I use?

ZIP and spatial data change over time, but silently replacing package data can change already-published analyses. zipcodeR therefore separates the historical contract from corrected, versioned behavior.

For a new analysis, use the _ng functions with an explicitly selected modern bundle. This is the forward-looking interface documented for new community code. Calling an _ng function communicates that the analysis opted into the bundle's newer data and semantics; it does not opt into automatic future updates. Keep the version and SHA pinned for the life of the project.

Use the unsuffixed functions when maintaining, rerunning, or comparing existing zipcodeR code. They are the historical compatibility interface.

All names that existed in 0.3.5 keep the same data, algorithm, ordering, rounding, warnings, errors, and unusual edge cases. This is intentional even where a behavior would be designed differently today.

zip_distance("08731", "08901")
get_cd("08731")
reverse_zipcode(c("08731", "08999", "08731"))
zip_data_version()

The returned metadata identifies the legacy snapshot. No option or network state can switch these functions to newer data.

Start a new analysis by pinning a modern bundle

A data release contains one RDS bundle and a JSON manifest. The manifest lists the bundle SHA256, every raw source URL and SHA256, licenses, vintages, build commit and R version, dependency-lock checksum, schemas, row counts, and canonical output hashes.

After a version has been published and registered, download it explicitly:

bundle <- download_zip_data_bundle("2026.09")

For offline or archival work, keep the RDS file with the project and verify the manifest checksum while reading it:

bundle <- read_zip_data_bundle(
  "data/zipcodeR-data-2026.09.rds",
  sha256 = "SHA256_FROM_THE_RELEASE_MANIFEST"
)

Aliases such as latest are rejected. A lookup never downloads a missing bundle or falls back to a different version.

Use the `_ng` interface

Every data-dependent next-generation function takes the bundle first:

reverse_zipcode_ng(bundle, c("08731", "08999", "08731"))
geocode_zip_ng(bundle, c("08731", "08999", "08731"))
search_radius_ng(bundle, 39.9, -74.3, radius = 10)
zip_distance_ng(bundle, "08731", "08901")
get_tracts_ng(bundle, "08731")
get_cd_ng(bundle, "08731")

These functions preserve input order and duplicates, make missing records explicit, validate inputs consistently, keep geographic identifiers as characters, and use the bundle's declared authoritative mappings and vintage. USPS-only ZIPs without an authoritative district relationship remain unmapped with a quality reason.

Recording provenance in research outputs

Store the complete version record, not merely the human-readable version:

version_record <- zip_data_version(bundle)
saveRDS(version_record, "results/zipcodeR-data-version.rds")

version_record$data_version
version_record$bundle_sha256
zip_data_provenance(bundle, dataset = "zip_to_cd", key = "08731")

For a reproducibility supplement, retain the release manifest, the bundle, and the analysis code together. The verified bundle_sha256 attribute is added by read_zip_data_bundle() and download_zip_data_bundle() and is propagated to _ng lookup results.