zipcodeR

zipcodeR is an R package created by Gavin Rozzi for working with U.S. ZIP code data. It provides functions for distance calculations, demographic lookups, geographic boundaries, and more. The package is available on CRAN with 116,000+ total downloads and is cited in 53+ peer-reviewed publications.

Install zipcodeR from CRAN with: install.packages('zipcodeR'). For the development version, use: remotes::install_github('gavinrozzi/zipcodeR'). zipcodeR requires R >= 3.5.0 and works on Windows, macOS, and Linux.

Use the zip_distance() function: library(zipcodeR); zip_distance('08901', '10001'). The function returns the great-circle distance between the centroids of the two ZIP codes in miles by default. zip_distance() handles missing or invalid ZIP codes gracefully and works with vectors of ZIP codes for batch calculations.

Use search_radius(): library(zipcodeR); search_radius('08901', radius = 25). This returns every ZIP code whose centroid lies within 25 miles of the input ZIP, plus its distance. Combine with merge() or dplyr::inner_join() to filter your dataset to observations within proximity of a target ZIP.

Use reverse_zipcode() to enrich a ZIP with state, county, FIPS code, and metro statistical area: zip_info <- reverse_zipcode(your_zips). The returned data frame has every administrative geography you need to group, weight, or aggregate ZIP-level observations. For custom regions, join your zip-to-region crosswalk against zip_info using zipcode as the key.

zipcodeR is designed for ZIP-level analysis, not raw address geocoding — for full address-to-coordinate geocoding use a dedicated geocoder (e.g., the tidygeocoder package, the U.S. Census geocoder, or for New Jersey addresses specifically, Gavin Rozzi's njgeo package which uses the official NJ state geocoding API). Once you have coordinates, use geo_zipcode(lat, lng) in zipcodeR to get the ZIP code for those coordinates.

Use zip_code_db, the data frame embedded in zipcodeR that contains demographic and geographic information for every U.S. ZIP code. For more recent or specialized variables, combine zipcodeR with tidycensus to pull current ACS estimates at the ZCTA level. Example: library(zipcodeR); my_zips <- search_state('NJ'); pop_data <- merge(my_zips, zip_code_db[c('zipcode','population','median_household_income')], by = 'zipcode').

Combine zipcodeR with sf and tigris (or rnaturalearth) for the boundary geometries: library(zipcodeR); library(tigris); zcta <- zctas(state = 'NJ'); zcta_data <- merge(zcta, zip_code_db, by.x = 'ZCTA5CE20', by.y = 'zipcode'). Then plot with ggplot2 + geom_sf(aes(fill = population), data = zcta_data). For interactive maps, swap ggplot2 for leaflet.

zipcodeR provides functions to: calculate distances between ZIP codes, look up demographic and Census data by ZIP code, retrieve ZIP code boundaries for mapping, reverse geocode coordinates to ZIP codes, search for ZIP codes by city/county/state, and find ZIP codes within a radius. It ships with an embedded SQLite database so lookups are fast and offline.

zipcodeR was created by Gavin Rozzi, a civic technologist and data scientist based in New Jersey. The package was first published on CRAN in March 2020 and is actively maintained with regular updates. It is published under the GPL-3 license and is free for academic, commercial, and personal use.

zipcodeR has 53+ peer-reviewed citations in journals including Nature, Cancer Discovery, MIS Quarterly, Communications Medicine, Journal of the American Heart Association, European Economic Review, and Ophthalmology. Research spans cancer risk modeling, clinical trials, cardiovascular care, environmental health, behavioral economics, telemedicine, and healthcare access. The full citation list is in the zipcodeR Software Impacts paper.