Skip to content

Light, fast, tree-based way to get cities by zipcode and location.


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



40 Commits

Repository files navigation

zips Travis status

Light, fast, tree-based way to get cities by zipcode and location.

npm install zips
const zips = require("zips");

U.S. postal codes only. For now.

zips.getByZipCode(zipcode: string)

If zipcode is found, returns a place object with zipcode, city, state, lat, long. Returns null if zipcode not found.

zips.getByLocation(lat: float, long: float)

Returns the closest place object to the specified coordinates.

Under the hood

zips doesn't load its data until the first time a function is called. The longest loading time I've seen is 100ms. After that, sub-millisecond returns can be expected.


I saw a lot of zip database modules on npm, but I was displeased with three aspects:

  • Old data (zips uses US Postcode data from, the most up-to-date I could find).
  • Huge, raw data (zips' data is pre-processed so it can just load and go).
  • List searching (zips organizes its data into trees instead of going down a list until a match is found or a large hash table).

I hope you're happy too.


  1. Download from GeoNames Postcodes Download Server
  2. Extract US.txt to root.
  3. npm run update.

Last update: 2023-02-03