zipcodes-plus

Fast, zero-dependency US ZIP code and Canadian postal code lookup — city, state/province, county, and coordinates. Ships ESM and CommonJS builds with TypeScript types.

Install

npm install zipcodes-plus

Usage

// ESM
import zipcodes, { find, findByCity, findByRadius } from "zipcodes-plus"

// CommonJS
const zipcodes = require("zipcodes-plus")
const { find } = require("zipcodes-plus")

find("90210")
// {
//   city: 'Beverly Hills', state: 'California', stateCode: 'CA',
//   county: 'Los Angeles', country: 'US',
//   placeName: 'Beverly Hills',
//   latitude: 34.0901, longitude: -118.4065, isValid: true
// }

find("M5V 3L9")
// {
//   city: 'Toronto', state: 'Ontario', stateCode: 'ON',
//   county: 'Toronto', country: 'CA',
//   placeName: 'Downtown Toronto (CN Tower / King and Spadina / ...)',
//   latitude: 43.6404, longitude: -79.3995, isValid: true
// }

You never pass a country. US ZIPs are five digits and Canadian codes start with a letter, so the format identifies the country. Canadian input is accepted in any shape — "M5V", "M5V 3L9", "m5v3l9" all resolve to the same record.

Canadian codes

Canadian results are at FSA granularity — the first three characters (M5V), a neighbourhood or small town. Passing a full six-character code works and returns its FSA record. Full six-character data is licensed by Canada Post and is not included.

city is the municipality. placeName is the raw GeoNames label, which for Canada describes the FSA's delivery area.

find("M5V 3L9").city        // 'Toronto'
find("M5V 3L9").placeName   // 'Downtown Toronto (CN Tower / ...)'

API

| Function | Returns | |---|---| | find(code) | { city, placeName, state, stateCode, county, country, latitude, longitude, isValid } | | findState(code) | { state, stateCode, country, isValid } | | findCity(code) | { city, isValid } | | findCounty(code) | { county, isValid } | | findCoordinates(code) | { latitude, longitude, isValid } | | isValid(code) | boolean | | countryOf(code) | "US" | "CA" | null | | findByCity(city, stateCode) | ZipCodeInfo[] | | findByCounty(county, stateCode) | ZipCodeInfo[] | | findByRadius(lat, lng, radius, unit?) | ZipCodeInfo[], nearest first | | getStates(country?) | [{ code, name, country }] | | getProvinces() | Canadian provinces and territories |

findByCity("Boston", "MA")
findByCity("Vancouver", "BC")
findByCounty("Los Angeles", "CA")
findByRadius(45.5017, -73.5673, 5, "km")   // "km" or "mi"; defaults to "mi"
getStates("US")
getProvinces()

State and province codes never collide, so findByCity and findByCounty need no country argument.

"CA" is California's state code, not Canada's. Country codes appear only in the country field and in getStates(country).

TypeScript

import { find, type ZipCodeInfo, type Country } from "zipcodes-plus"

Exported types: ZipCodeInfo, ZipLookupResult, StateResult, Coordinates, Country, DistanceUnit.

Credits and licence

A fork of zipcodes-us by Karthik Gangadharaiah, with Canadian postal code support added.

Postal code data from GeoNames, licensed CC BY 4.0.

Code is MIT. See LICENSE.