zip-state

ZIP-State

zip-state is a lightweight mapping of USPS-defined ZIP Codes to their assigned regions. Given a 5- or 9-digit ZIP Code, zip-state will return the USPS abbreviation for the corresponding region. It is well suited for quick real-time checking of user address input and validating the most significant digits of the ZIP code.

For example, the user enters WI for their region but 63005 for their ZIP Code (belonging to MO) instead of 53005, the discrepancy can be instantly detected.

See an in-browser example.

Every real ZIP Code will work. However, it is not a comprehensive listing. In most cases it will not check the complete input, only the first three digits that form the prefix. If that prefix range is in-use, non-existent ZIP Codes may still return that region. For example, 83005 will match Wyoming (830 prefix), even though that specific ZIP Code does not (currently) exist. It also currently does not support Canadian or other non-US postal codes. See Alternatives below for other options.

Note: this is using the USPS mapping and is based on how ZIPs are used for US mail routing and delivery. The USPS does not define geographic boundaries for ZIP Codes. The region found will not necessarily match how the US Census Bureau uses ZIP Codes for their ZIP Code Tabulation Areas, or correspond to actual geographic location. Particularly, some ZCTAs cross state lines, eg 81137. This library may be helpful for rough geographic validation, but should not be relied on for precise geolocation. Check out the tests for some fun exceptions to the assignments.

Installation

npm install --save zip-state

and include as a JavaScript or TypeScript module (types included):

import zipState from 'zip-state';

…or a CommonJS module:

const zipState = require('zip-state');

Or use the file directly in markup using the unpkg CDN:

<script src="https://unpkg.com/zip-state"></script>

Usage

Pass the ZIP code to the function and get back the two-digit region abbreviation as a string, or null if no match.

const region = zipState('10001');
// region === 'NY';

const region = zipState('56800');
// region === null;

ZIP+4 will also work:

const region = zipState('10001-1234');
// region === 'NY'

Author

Alec Perkins, https://alecperkins.net

License

The packaged mapping and lookup function code, and published build tooling, is licensed under the Creative Commons “CC0 1.0 Universal” license.

See ./LICENSE for more information.

Acknowledgements

Assembled ZIP Code data is derived from the database provided by Daniel. S. Coven:

Coven, D. S., (2012). Free Zipcode Database: Unique Zipcode [data file]. Retrieved from http://federalgovernmentzipcodes.us

The assignments themselves are a product of the United States Postal Service, with which this project has no affiliation.

Alternatives

zip-state’s focus is bundle size and specific usecase, trading 100% comprehensiveness for tiny footprint but still handling all real ZIPs. zip-state is about 5 KB uncompressed, 1 KB compressed. Many of the alternatives are several MB in size, or do not include support for regions other than the 50 states and DC.

For comprehensive lookup, Canada support, and geographic mapping, check out zipcodes.

For reverse geocoding, try us-zips or zipsearch.