README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(tibble)
devtools::load_all(quiet = TRUE)
```

# zipcodeR <a href='https://zipcoder.39n.io/'><img src='man/figures/logo.png' align="right" height="139" /></a>

<!-- badges: start -->
[R-CMD-check](https://github.com/gavinrozzi/zipcodeR/actions) ·
[Codecov](https://app.codecov.io/gh/gavinrozzi/zipcodeR) ·
[CRAN release](https://cran.r-project.org/package=zipcodeR) ·
[CRAN downloads](https://cranlogs.r-pkg.org/downloads/total/last-month/zipcodeR)
<!-- badges: end -->

### 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.](https://zipcoder.39n.io/articles/geographic.html)

## Installation

You can install the released version of zipcodeR from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("zipcodeR")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# 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:

```{r}
zip_distance("08731", "08901")
get_cd("08731")
zip_data_version()
```

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:

```{r, eval=FALSE}
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](https://www.sciencedirect.com/science/article/pii/S2665963821000373/).

A BibTeX entry for LaTeX users is:

```bibtex
@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

```{r, eval=FALSE}
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.](https://zipcoder.39n.io/)
See the [reference section](https://zipcoder.39n.io/reference/) for full details on how to use each of the functions provided by zipcodeR.

## Data Sources
This project was inspired by the excellent [uszipcode](https://uszipcode.readthedocs.io/index.html) 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.