Package 'zipcodeR'

Description

The bundled zip_code_db is the lightweight ("simple") dataset. A much larger companion database with detailed ACS demographic profiles per ZIP code (the "comprehensive" database, ~450 MB SQLite) is published as a checksum-pinned asset of a zipcodeR data release rather than shipped in the package. Its public URL, checksum, and SQLite integrity have passed a clean-machine smoke test.

Usage

download_comprehensive_data(force = FALSE)

Arguments

Details

This function downloads that database, verifies its SHA256 checksum, and, on R 4.0 or newer, caches it under tools::R_user_dir("zipcodeR", "data"); later calls return the cached path immediately. On older supported R versions the verified file is kept only in the session temporary directory. It never downloads without being called explicitly. For offline use on R 4.0 or newer, copy the file to that user data directory yourself (the expected file name is the asset name from the data release).

Value

Invisibly, the path to the downloaded SQLite database. Query it with DBI/RSQLite, e.g. DBI::dbConnect(RSQLite::SQLite(), download_comprehensive_data()).

Examples

## Not run: 
path <- download_comprehensive_data()

## End(Not run)

Description

This function is retained without behavioral changes for reproducibility with zipcodeR 0.3.5. It attempts to modify files inside an installed package and resolves an upstream "latest" release, so it is unsuitable for a pinned research workflow. New work should use download_zip_data_bundle() or read_zip_data_bundle() and pass the resulting object explicitly to the ⁠_ng⁠ API. No runtime warning is emitted because warnings are part of the frozen legacy contract.

Usage

download_zip_data(force = FALSE)

Arguments

Value

Data files needed for package functionality, stored in data directory of package install

Examples

## Not run: 
download_zip_data()

## End(Not run)

Description

Downloads one explicitly requested data release, verifies its checksum, and caches it in the user's data directory on R 4.0 or newer. On older supported R versions, CRAN policy does not permit a package-managed persistent cache, so the verified file is retained only for the current R session. The function never resolves aliases such as "latest", and no lookup function downloads data implicitly.

Usage

download_zip_data_bundle(version, force = FALSE)

Arguments

Value

A validated zipcodeR_data_bundle.

Description

Returns that lat / lon pair of the centroid of a given ZIP code

Usage

geocode_zip(zip_code)

Arguments

Value

tibble of lat lon coordinates

Examples

geocode_zip("07762")
geocode_zip("90210")
geocode_zip("90210")$lat
geocode_zip("90210")$lng

Description

Geocode ZIP codes using an explicit data bundle

Usage

geocode_zip_ng(data, zip_code)

Arguments

Value

One coordinate row per input, preserving order and duplicates.

Description

Get all congressional districts for a given ZIP code

Usage

get_cd(zip_code)

Arguments

Value

a named list of two-digit state code and two digit district code

Examples

get_cd("08731")
get_cd("90210")

Description

Get congressional districts using an explicit data bundle

Usage

get_cd_ng(data, zip_code)

Arguments

Value

A named list with parallel state_fips and district vectors.

Description

Get all Census tracts within a given ZIP code

Usage

get_tracts(zip_code)

Arguments

Value

tibble of Census tracts and data from Census crosswalk file found for given ZIP code

Examples

get_tracts("08731")
get_tracts("90210")

Description

Get Census tracts using an explicit data bundle

Usage

get_tracts_ng(data, zip_code)

Arguments

Value

A tract crosswalk tibble.

Description

Returns true if the given ZIP code is also a ZIP code tabulation area (ZCTA)

Usage

is_zcta(zip_code)

Arguments

Value

Boolean TRUE or FALSE based upon whether provided ZIP code is a ZCTA by testing whether it exists in the U.S. Census crosswalk data

Examples

is_zcta("90210")
is_zcta("99999")
is_zcta("07762")

Description

Test ZCTA membership using an explicit data bundle

Usage

is_zcta_ng(data, zip_code)

Arguments

Value

A logical vector.

Description

Normalize ZIP codes

Usage

normalize_zip(zipcode)

Arguments

Value

Normalized zipcode

Examples

normalize_zip(0008731)

Description

Normalize ZIP codes with corrected boundary behavior

Usage

normalize_zip_ng(zipcode)

Arguments

Value

Normalized five-character ZIP values.

Description

Reads and validates a previously downloaded zipcodeR data bundle. Bundles are explicit, immutable inputs for the next-generation (⁠_ng⁠) API; reading one never changes the datasets used by the legacy API.

Usage

read_zip_data_bundle(path, sha256 = NULL)

Arguments

Value

An object of class zipcodeR_data_bundle.

Description

Given a ZIP code, returns columns of metadata about that ZIP code

Usage

reverse_zipcode(zip_code)

Arguments

Value

A tibble containing data for the ZIP code(s)

Examples

reverse_zipcode("90210")
reverse_zipcode("08731")
reverse_zipcode(c("08734", "08731"))
reverse_zipcode("07762")$county
reverse_zipcode("07762")$state

Description

Reverse-geocode ZIP codes using an explicit data bundle

Usage

reverse_zipcode_ng(data, zip_code)

Arguments

Value

One row per input, in input order, with duplicates preserved. The result adds state_fips (two digits) and county_fips (the full five-digit county identifier) for the database's predominant county.

Description

Get all ZIP codes that fall within a given congressional district

Usage

search_cd(state_fips_code, congressional_district)

Arguments

Value

tibble of all congressional districts found for given ZIP code, including state code

Examples

search_cd("34", "03")
search_cd("36", "05")

Description

Search a congressional district using an explicit data bundle

Usage

search_cd_ng(data, state_fips_code, congressional_district)

Arguments

Value

A ZIP-to-district tibble.

Description

Search ZIP codes for a given city within a state

Usage

search_city(city_name, state_abb)

Arguments

Value

tibble of all ZIP code data found for given city

Examples

search_city("Spring Lake", "NJ")
search_city("Chappaqua", "NY")

Description

Search a city using an explicit data bundle

Usage

search_city_ng(data, city_name, state_abb)

Arguments

Value

A tibble from the selected data vintage.

Description

Search ZIP codes for a county

Usage

search_county(county_name, state_abb, ...)

Arguments

Value

tibble of all ZIP codes for given county name

Examples

middlesex <- search_county("Middlesex", "NJ")
alameda <- search_county("alameda", "CA")
search_county("ST BERNARD", "LA", similar = TRUE)$zipcode

Description

Search a county using an explicit data bundle

Usage

search_county_ng(data, county_name, state_abb, ...)

Arguments

Value

A tibble from the selected data vintage.

Description

Returns all ZIP codes found within a given FIPS code

Usage

search_fips(state_fips, county_fips)

Arguments

Value

tibble of Census tracts and data from Census crosswalk file found for given ZIP code

Examples

search_fips("34")
search_fips("34", "03")
search_fips("34", "3")
search_fips("36", "003")

Description

Search FIPS codes using an explicit data bundle

Usage

search_fips_ng(data, state_fips, county_fips)

Arguments

Value

A tibble from the selected data vintage.

Description

Search for ZIP codes that are within a given radius from a point

Usage

search_radius(lat, lng, radius = 1)

Arguments

Value

a tibble containing the ZIP code(s) within the provided radius and distance from the provided coordinates in miles

Examples

## Not run: 
search_radius(39.9, -74.3, 10)

## End(Not run)

Description

Search within a radius using an explicit data bundle

Usage

search_radius_ng(data, lat, lng, radius = 1)

Arguments

Value

A tibble of ZIP codes and haversine distances.

Description

Search for ZIP codes located within a given state

Usage

search_state(state_abb)

Arguments

Value

tibble of all ZIP codes for each state code defined in state_abb

Examples

search_state("NJ")
search_state(c("NJ", "NY", "CT"))

Description

Search a state using an explicit data bundle

Usage

search_state_ng(data, state_abb)

Arguments

Value

A tibble grouped in query order; repeated states repeat their rows.

Description

Search all ZIP codes located within a given timezone

Usage

search_tz(tz)

Arguments

Value

tibble of all ZIP codes found for given timezone

Examples

eastern <- search_tz("Eastern")
pacific <- search_tz("Mountain")

Description

Search a timezone using an explicit data bundle

Usage

search_tz_ng(data, tz)

Arguments

Value

A tibble grouped in query order; repeated timezones repeat their rows.

Description

A dataset containing the relationships between ZIP code tabulation areas (ZCTA) and Census Tracts. This contains selected variables from the official crosswalk file.

Usage

zcta_crosswalk

Format

A data frame with 148897 rows and 3 variables:

ZCTA5

2010 ZIP Code Tabulation Area

TRACT

2010 Census Tract Code

GEOID

Concatenation of 2010 State, County, and Tract

Details

This is the exact dataset distributed by zipcodeR 0.3.5. It is intentionally frozen so legacy calls remain reproducible; newer versioned relationships are available only through an explicit data bundle and the ⁠_ng⁠ API.

Source

https://www.census.gov/geographies/reference-files/time-series/geo/relationship-files.html

Description

A dataset containing detailed information for U.S. ZIP codes

Usage

zip_code_db

Format

A data frame with 41877 rows and 24 variables:

zipcode

5 digit U.S. ZIP code

zipcode_type

ZIP category such as Standard, PO Box, or Unique

major_city

Major city serving the ZIP code

post_office_city

City of post office serving the ZIP code

common_city_list

List of common cities represented by the ZIP code

county

Name of county containing the ZIP code

state

Two-digit state code for ZIP code location

lat

Latitude of the centroid for the ZIP code

lng

Longitude of the centroid for the ZIP code

timezone

Timezone of the ZIP code

radius_in_miles

Radius of the ZIP code in miles

area_code_list

List of area codes for telephone numbers within this ZIP code

population

Total population of the ZIP code

population_density

Population density of the ZIP code (persons per square mile)

land_area_in_sqmi

Area of the land contained within the ZIP code in square miles

water_area_in_sqmi

Area of the waters contained within the ZIP code in square miles

housing_units

Number of housing units within the ZIP code

occupied_housing_units

Number of housing units within the ZIP code

median_home_value

Median home price within the ZIP code

median_household_income

Median household income within the ZIP code

bounds_west

Bounding box coordinates

bounds_east

Bounding box coordinates

bounds_north

Bounding box coordinates

bounds_south

Bounding box coordinates

Details

This is the exact 41,877-row database distributed by zipcodeR 0.3.5, including its historical values and limitations. It is intentionally frozen for research reproducibility. Use an explicit data bundle with ⁠_ng⁠ functions for corrected behavior and a pinned source manifest.

Source

https://github.com/MacHu-GWU/uszipcode-project/files/5183256/simple_db.log

Description

Inspect the provenance supplied with a zipcodeR data bundle

Usage

zip_data_provenance(bundle, dataset = NULL, key = NULL)

Arguments

Value

A provenance data frame combining source/method records with record-level quality status and reasons.

Description

With no argument, reports the immutable data bundled with the legacy API. Given a downloaded data bundle, reports that bundle's metadata and verified checksum.

Usage

zip_data_version(x = NULL)

Arguments

Value

A named metadata list.

Description

Calculate the distance between two ZIP codes in miles

Usage

zip_distance(zipcode_a, zipcode_b, lonlat = TRUE, units = "miles")

Arguments

Value

a data.frame containing a column for each ZIP code and a new column containing the distance between the two columns of ZIP code

Examples

zip_distance("08731", "08901")

Description

Calculate ZIP-to-ZIP distance using an explicit data bundle

Usage

zip_distance_ng(
  data,
  zipcode_a,
  zipcode_b,
  lonlat = TRUE,
  units = c("miles", "meters")
)

Arguments

Value

A data frame of paired ZIP codes and distances.

Description

A dataset containing mappings between ZIP codes and congressional districts

Usage

zip_to_cd

Format

A data frame with 45914 rows and 2 variables:

ZIP

5 digit U.S. ZIP code

CD

Four digit congressional district code (State FIPS code + district number)

Details

This is the exact pre-2020 HUD-USPS-derived mapping shipped in zipcodeR 0.3.5. It is frozen for legacy reproducibility and should not be interpreted as a current redistricting vintage. Current authoritative ZCTA relationships are available in explicit data bundles.

Source

Historical HUD-USPS-derived snapshot archived at https://github.com/gavinrozzi/zipcodeR-data