zip-state
v1.0.3
Published
Lightweight mapping of USPS ZIP Codes to their assigned region.
Downloads
55,374
Maintainers
Readme
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.
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
.