us-zips

us-zips :us:

A list of US ZIP codes and their geolocations

I needed a list of ZIP codes, and the US Census Bureau had one.

Usage

Example: get the nearest zip to a geolocation

const geolib = require('geolib')
const usZips = require('us-zips')

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

geolib.findNearest(somewhere, usZips) // { distance: 12834, key: '39341' }

:information_source: If you need the nearest ZIPs for a geolocation, see if geo2zip fits your needs. It is much faster than the demo above and uses this package as a source.

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

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

:information_source: 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.

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

• blakek/geo2zip - get the nearest zip code from a geolocation
• blakek/standardize-geolocation - takes geolocations of different formats and outputs a standardized version
• US Census Bureau - map data page

License

MIT