js-zip-code-locator

Node.js module for US ZIP code lookups: full data, coordinates, lookup by city/state, closest zips by radius, data by coordinates, distance between zips, state/city discovery, validation, bounding box, and more. Distances can be in miles (default) or kilometers.

Installable as a dependency in other projects.

Install

npm install js-zip-code-locator

Usage

The module initializes with an optional unit: miles (default) or kilometers.

const createZipLocator = require('js-zip-code-locator');

// Default: distances in miles
const locator = createZipLocator();

// Distances in kilometers
const locatorKm = createZipLocator({ useMiles: false });

You can also use the default instance without calling the factory:

const zipLocator = require('js-zip-code-locator');
zipLocator.getZipData('10001');

API Reference

Lookup by ZIP

| Method | Description | |--------|-------------| | getZipData(zipCode) | Full record: state, city, lat, lng, and full state name. One object or undefined. | | getZipCoordinates(zipCode) | { latitude, longitude } or undefined. | | getCityState(zipCode) | { city, state, formatted: "City, ST" } or undefined. For labels. | | isValidZip(zipCode) | true if the zip exists in the dataset, false otherwise. |

Lookup by city / state

| Method | Description | |--------|-------------| | getZipCodes(city, state) | All zip codes (with coordinates) for a city and state. Array; can be multiple. | | getZipsInState(state) | All zip codes (with coordinates) in a state. | | getCitiesInState(state) | Unique city names in a state, sorted. | | getFullStateName(stateAbbr) | Full state name for abbreviation (e.g. 'AL' → 'Alabama'). |

Search and filters

| Method | Description | |--------|-------------| | searchZipPrefix(prefix) | Zips whose code starts with prefix (e.g. '100' for NYC area). | | getZipsInBoundingBox(minLat, maxLat, minLng, maxLng) | All zips inside the given rectangle (e.g. map viewport). |

Distance and radius

| Method | Description | |--------|-------------| | getClosestByZipCode(zipCode, radius, useMiles?) | Zips within radius of a zip, with distance. Unit: instance default or override. | | getDataByCoordinates(lat, lng, options?) | All zips with distance from (lat, lng). Options: { sort: 'distance' \| 'zip' \| 'city' }. | | getDistanceBetweenZipCodes(zip1, zip2, useMiles?) | Distance between two zips. undefined if either zip not found. | | getDistancesFromZip(originZip, zipCodes, useMiles?) | Distances from one origin zip to many zips in one call. |

Examples

By ZIP code

const locator = createZipLocator();

locator.getZipData('35004');
// { zip: '35004', latitude: 33.606379, longitude: -86.50249, city: 'Moody', state: 'AL', full: 'Alabama' }

locator.getZipCoordinates('35004');
// { latitude: 33.606379, longitude: -86.50249 }

locator.getCityState('35004');
// { city: 'Moody', state: 'AL', formatted: 'Moody, AL' }

locator.isValidZip('35004');   // true
locator.isValidZip('99999');   // false

By city and state

locator.getZipCodes('Moody', 'AL');
// [ { zip: '35004', latitude: ..., longitude: ..., city: 'Moody', state: 'AL', full: 'Alabama' }, ... ]

locator.getZipsInState('AL');
// [ { zip: '35004', ... }, { zip: '35005', ... }, ... ]  (all zips in Alabama)

locator.getCitiesInState('AL');
// [ 'Adamsville', 'Adger', 'Alabaster', 'Alexander City', ... ]

locator.getFullStateName('AL');   // 'Alabama'
locator.getFullStateName('al');   // 'Alabama'

Search and bounding box

locator.searchZipPrefix('100');
// [ { zip: '10001', ... }, { zip: '10002', ... }, ... ]  (NYC area)

locator.getZipsInBoundingBox(33.5, 34, -87, -86);
// [ { zip: '35004', ... }, ... ]  (zips inside the lat/lng rectangle)

Distance and radius

locator.getClosestByZipCode('35004', 10);
// [ { zip: '35004', ..., distance: 0 }, { zip: '35005', ..., distance: 5.2 }, ... ]

locator.getClosestByZipCode('35004', 16, false);  // radius and distance in km

locator.getDataByCoordinates(33.6, -86.5, { sort: 'distance' });
// [ { zip: '...', ..., distance: 2.1 }, ... ]

locator.getDataByCoordinates(33.6, -86.5, { sort: 'zip' });   // sort by zip
locator.getDataByCoordinates(33.6, -86.5, { sort: 'city' });  // sort by city

locator.getDistanceBetweenZipCodes('35004', '35007');
// 12.34 (miles)

locator.getDistanceBetweenZipCodes('35004', '35007', false);
// 19.86 (km)

locator.getDistancesFromZip('35004', ['35007', '35005', '99999']);
// [ { zip: '35007', distance: 12.34 }, { zip: '35005', distance: 5.2 }, { zip: '99999', distance: undefined } ]

Custom data file

const locator = createZipLocator({ dataPath: '/path/to/zip-codes.json' });

Expected JSON format: array of objects with zip, latitude, longitude, city, state, and optional full.

Testing this project locally

1. Clone and install (if not already):

   cd js-zip-code-locator
   npm install

2. Run the test suite:

   npm test

   This runs Node’s built-in test runner (node --test) on the files in test/. No extra test framework is required.

3. Run a single test file (optional):

   node --test test/index.js

4. Try the API in Node (optional):

   node -e "
   const createZipLocator = require('.');
   const locator = createZipLocator();
   console.log(locator.getZipData('35004'));
   console.log(locator.getCityState('35004'));
   console.log(locator.getFullStateName('AL'));
   console.log(locator.getDistanceBetweenZipCodes('35004', '35007'));
   "

Contributing

Contributions are welcome. Anyone can contribute.

• Open an issue to discuss changes or report bugs
• Submit pull requests for fixes or new features
• Ensure tests pass with npm test before submitting

License

MIT