Skip to content

Latest commit

 

History

History
143 lines (100 loc) · 4.21 KB

README.md

File metadata and controls

143 lines (100 loc) · 4.21 KB
Raw

us-zips 🇺🇸

A list of US ZIP codes and their geolocations

A list of United States ZIP Codes based on the US Census Bureau's ZIP Code Tabulation Areas (ZCTAs).

💁 Before using ZIP codes, there's helpful points to know:

  • USPS ZIP codes are short and memorable, but they aren't very good for geolocation. Their main use is for local mail routes.
  • ZIP codes change with mail routes. They're reused, sometimes for different locations.
  • The ZIP used for mail delivery may not be the closest (or even second closest) ZIP by linear distance. This may be due to terrain, political borders, etc.
  • One physical location could be served by multiple ZIP codes

📦 This package:

uses ZIP Code Tabulation Areas (ZCTAs) : Some ZIP codes used by the USPS are not included, such as those with no or very few residential addresses.

uses the center of the ZCTA polygon : This keeps the package smaller, more performant, and simpler to use. ZIP codes aren't very good for geolocation anyway, so we chose to keep the amount of data loaded in memory to a minimum.

stays up-to-date with the Census Bureau's data : After new data is published, this package is updated soon. Unlike several other ZIP lists, this one purges outdated information.

Usage

Example: get the nearest ZIP to a geolocation

ℹ️ If you need the nearest ZIPs for a geolocation, check out geo2zip. It is much faster than the demo below and uses this package.

const geolib = require("geolib");
const usZips = require("us-zips/array");

const somewhere = {
	lat: 33.1234,
	lng: -88.4321,
};

geolib.findNearest(somewhere, usZips);
//» { latitude: 33.088581, longitude: -88.556133, zipCode: "39341" }

Data Formats

Default (Object)

The default export returns an object. The object's keys are each ZIP code and values are objects with latitude and longitude properties.

const usZips = require('us-zips')

console.log(usZips['54301'])
//» { latitude: 44.480778, longitude: -88.016063 }

// Shape
{
  …
  '54301': { latitude: 44.480778, longitude: -88.016063 }
  …
}

Array

const usZips = require('us-zips/array')

console.log(usZips.find(zip => zip.zipCode === '37214'))
//» { latitude: 36.162189, longitude: -86.670867, zipCode: '37214' }

// Shape
[
  …
  {
    latitude: 36.162189,
    longitude: -86.670867,
    zipCode: '37214'
  },
  …
]

Key/value

const usZips = require('us-zips/key-value')

console.log(usZips.find(([key, value]) => key === '10001'))
//» ['10001', { latitude: 40.750634, longitude: -73.997176 }]

// Shape
[
  …
  ['10001', { latitude: 40.750634, longitude: -73.997176 }],
  …
]

Map

const usZips = require("us-zips/map");

console.log(usZips.get("90210"));
//» { latitude: 34.100517, longitude: -118.41463 }

Install

With Yarn or npm installed, run:

yarn add us-zips@2022.09

# ...or, if using `npm`
npm install us-zips@2022.09

ℹ️ NOTE: Due to ZIP codes always changing, this package uses calendar versioning (aka CalVer). This means each year will have a separate "major" version from npm and Yarn's perspective. However, breaking changes could occur on minor versions. We suggest pinning to the minor version you want to use (e.g. yarn add us-zips@2022.09).

Acknowledgments

Data for ZIP codes and their geolocations was generated from this file, which can be downloaded from the US Census Bureau map data page.

See Also

License

MIT