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)
```

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

<!-- badges: start -->
[![R-CMD-check](https://github.com/gavinrozzi/zipcodeR/workflows/R-CMD-check/badge.svg)](https://github.com/gavinrozzi/zipcodeR/actions)
[![codecov](https://codecov.io/gh/gavinrozzi/zipcodeR/branch/master/graph/badge.svg?token=9HDL7QUPCE)](https://app.codecov.io/gh/gavinrozzi/zipcodeR)
[![CRAN Status](https://www.r-pkg.org/badges/version-last-release/zipcodeR)](https://www.r-pkg.org/badges/version-last-release/zipcodeR)
[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/zipcodeR)](https://cranlogs.r-pkg.org/badges/grand-total/zipcodeR)
[![CRAN Downloads Per Month](https://cranlogs.r-pkg.org/badges/last-month/zipcodeR)](https://cranlogs.r-pkg.org/badges/grand-total/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://gavinrozzi.github.io/zipcodeR/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")
```

## 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.}
}
```

## Examples


```{r}
# Load zipcodeR into R
library(zipcodeR)
```


### Find all ZIP codes for a state

```{r}
search_state('NJ')
```

### Calculate the distance between two ZIP codes in miles

```{r}
zip_distance('08901','08731')
```


### Calculate the distance between vectors of ZIP codes

```{r}
zip_codes <- tribble(~zip_a,  ~zip_b,
"08731",  "08901",
"08734",  "08005")

zip_distance(zip_codes$zip_a,zip_codes$zip_b)
```

### Geocode a ZIP code to get its centroid
```{r}
geocode_zip('08901')
```

### Get data about a ZIP code
```{r}
reverse_zipcode('08901')
```

### Find all ZIP codes for a county
```{r}
search_county('Ocean','NJ')
```


### Find all ZIP codes for a city
```{r}
search_city('Jersey City','NJ')
```

### Find all ZIP codes for a timezone
```{r}
search_tz('Eastern')
```

### Get all Census tracts for a given ZIP code
```{r}
get_tracts('08731')
```

## Documentation
Documentation for the current release [is available here.](https://gavinrozzi.github.io/zipcodeR/)
See the [reference section](https://gavinrozzi.github.io/zipcodeR/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.