zipcodes-us

A lightweight and efficient US ZIP code lookup library with no external dependencies.

I try my best to monitor the required dependencies daily and publish updates to the npm package whenever changes are detected.

🔄 Data Last Checked/Updated: 25th September 2026

Features

• Fast in-memory ZIP code lookups
• Multiple lookup methods for different use cases
• Find ZIP codes by city, state, and county
• Find ZIP codes within a radius of coordinates
• Returns complete information including state, city, county, and coordinates
• Universal compatibility - works in both Node.js and browser/React environments
• TypeScript support with full type definitions
• Zero runtime dependencies

Why Choose zipcodes-us?

• 🚀 Zero Dependencies - No bloat, just pure functionality
• ⚡ Lightning Fast - In-memory lookups with instant results
• 🌐 Universal - Same code works in Node.js, React, Next.js, and browsers
• 📦 Tiny Bundle - Minimal impact on your bundle size
• 🔄 Always Up-to-Date - Data checked and updated daily
• 💪 Type-Safe - Full TypeScript support out of the box
• 🎯 Battle-Tested - Reliable and production-ready

Compared to alternatives:

• Unlike zipcode-to-timezone, we provide complete geographic data
• Unlike zipcodes, we support both Node.js and browsers seamlessly
• Unlike manual API calls, no rate limits or network latency

🚀 Try It Now

Live Demo: CodeSandbox Demo

Quick Example:

import zipcodes from "zipcodes-us"

// One line to get complete ZIP code info
const info = zipcodes.find("90210")
// → { city: 'Beverly Hills', state: 'California', ... }

Installation

npm install zipcodes-us

Usage

This library works seamlessly in both Node.js and browser/React environments with no configuration needed.

Basic Usage

import zipcodes from "zipcodes-us"

// Complete lookup with validity check
const info = zipcodes.find("90210")
console.log(info)
/* Output:
{
  state: 'California',
  stateCode: 'CA',
  city: 'Beverly Hills',
  county: 'Los Angeles',
  latitude: 34.0901,
  longitude: -118.4065,
  isValid: true
}
*/

// For invalid ZIP codes, returns empty values with isValid: false
const invalid = zipcodes.find("00000")
console.log(invalid)
/* Output:
{
  state: '',
  stateCode: '',
  city: '',
  county: '',
  latitude: 0,
  longitude: 0,
  isValid: false
}
*/

// Get just the state information
const stateInfo = zipcodes.findState("10001")
console.log(stateInfo) // { state: 'New York', stateCode: 'NY', isValid: true }

// Get just the city
const cityInfo = zipcodes.findCity("60601")
console.log(cityInfo) // { city: 'Chicago', isValid: true }

// Get just the county
const countyInfo = zipcodes.findCounty("94105")
console.log(countyInfo) // { county: 'San Francisco', isValid: true }

// Get just the coordinates
const coords = zipcodes.findCoordinates("02108")
console.log(coords) // { latitude: 42.3588, longitude: -71.0707, isValid: true }

// Find ZIP codes for a city
const bostonZips = zipcodes.findByCity("Boston", "MA")
console.log(`Boston has ${bostonZips.length} ZIP codes`)

// Find ZIP codes in a county
const kingCountyZips = zipcodes.findByCounty("King", "WA")
console.log(`King County has ${kingCountyZips.length} ZIP codes`)

// Find ZIP codes within 10 miles of coordinates
const nearby = zipcodes.findByRadius(37.7749, -122.4194, 10)
console.log(`Found ${nearby.length} ZIP codes within 10 miles of San Francisco`)

// Get all states
const states = zipcodes.getStates()
console.log(`The US has ${states.length} states and territories with ZIP codes`)

Node.js Example

import zipcodes from "zipcodes-us"
import fs from "fs"

// Find all ZIP codes for a specific city
const bostonZips = zipcodes.findByCity("Boston", "MA")

// Save the data to a file
fs.writeFileSync("boston-zips.json", JSON.stringify(bostonZips, null, 2))

console.log(`Saved ${bostonZips.length} Boston ZIP codes to file`)

React/Browser Example

import React, { useState } from "react"
import zipcodes from "zipcodes-us"

function ZipCodeLookup() {
  const [zipCode, setZipCode] = useState("")
  const [result, setResult] = useState(null)
  const [error, setError] = useState("")

  const handleLookup = () => {
    setError("")
    const info = zipcodes.find(zipCode)

    if (info.isValid) {
      setResult(info)
    } else {
      setError("Invalid ZIP code")
      setResult(null)
    }
  }

  return (
    <div>
      <h2>ZIP Code Lookup</h2>
      <div>
        <input
          type="text"
          value={zipCode}
          onChange={(e) => setZipCode(e.target.value)}
          placeholder="Enter ZIP code"
          maxLength={5}
        />
        <button onClick={handleLookup}>Lookup</button>
      </div>

      {error && <div style={{ color: "red" }}>{error}</div>}

      {result && (
        <div>
          <h3>Results for {zipCode}</h3>
          <p>
            <strong>City:</strong> {result.city}
          </p>
          <p>
            <strong>State:</strong> {result.state} ({result.stateCode})
          </p>
          <p>
            <strong>County:</strong> {result.county}
          </p>
          <p>
            <strong>Coordinates:</strong> {result.latitude}, {result.longitude}
          </p>
        </div>
      )}
    </div>
  )
}

export default ZipCodeLookup

💡 Common Use Cases

Validate ZIP Codes

// Check if a ZIP code is valid
const info = zipcodes.find("90210")
if (info.isValid) {
  console.log(`Valid ZIP in ${info.city}, ${info.state}`)
}

Auto-Complete City/State from ZIP

// User enters ZIP, auto-fill city and state
const { city, state } = zipcodes.find(userZipCode)
addressForm.city.value = city
addressForm.state.value = state

Find All ZIP Codes in a City

// Get all ZIP codes for a specific city
const allBostonZips = zipcodes.findByCity("Boston", "MA")
console.log(`Boston has ${allBostonZips.length} ZIP codes`)

Geographic Proximity Search

// Find ZIP codes within 50 miles of coordinates
const nearbyZips = zipcodes.findByRadius(37.7749, -122.4194, 50)
// Use these for location-based features

Display Location Information

// Show detailed location info from just a ZIP code
const info = zipcodes.find("10001")
displayMap(info.latitude, info.longitude)
showDetails(`${info.city}, ${info.county} County, ${info.state}`)

API

find(zipCode: string): ZipLookupResult

Returns complete information for a ZIP code with an isValid flag. Always returns an object, even for invalid ZIP codes.

interface ZipLookupResult {
  state: string // Full state name
  stateCode: string // Two-letter state code
  city: string // City/place name
  county: string // County name
  latitude: number // Decimal latitude
  longitude: number // Decimal longitude
  isValid: boolean // Whether the ZIP code exists
}

// Internal ZipCodeInfo interface used by findByCity, findByCounty, and findByRadius methods
interface ZipCodeInfo {
  zipCode: string // 5-digit ZIP code
  placeName: string // City or place name
  stateName: string // Full state name
  stateCode: string // Two-letter state code
  countyName: string // County name
  countyCode: string // FIPS county code
  communityName?: string // Optional community name
  communityCode?: string // Optional community code
  latitude: number // Latitude in decimal degrees
  longitude: number // Longitude in decimal degrees
}

findState(zipCode: string): StateResult

Returns state information for a ZIP code with validity check.

interface StateResult {
  state: string // Full state name
  stateCode: string // Two-letter state code
  isValid: boolean // Whether the ZIP code exists
}

findCity(zipCode: string): { city: string; isValid: boolean }

Returns city name for a ZIP code with validity check.

findCounty(zipCode: string): { county: string; isValid: boolean }

Returns county name for a ZIP code with validity check.

findCoordinates(zipCode: string): Coordinates

Returns latitude and longitude for a ZIP code with validity check.

interface Coordinates {
  latitude: number // Decimal latitude
  longitude: number // Decimal longitude
  isValid: boolean // Whether the ZIP code exists
}

findByCity(city: string, stateCode: string): ZipCodeInfo[]

Finds all ZIP codes for a given city and state. Returns an array of ZipCodeInfo objects.

findByCounty(countyName: string, stateCode: string): ZipCodeInfo[]

Finds all ZIP codes in a given county. Returns an array of ZipCodeInfo objects.

findByRadius(latitude: number, longitude: number, radiusMiles: number): ZipCodeInfo[]

Finds ZIP codes within a radius of coordinates, sorted by distance. Returns an array of ZipCodeInfo objects.

getStates(): Array<{ code: string, name: string }>

Returns all states with their codes and names.

How Browser Compatibility Works

The ZIP code data is bundled into the package at build time, so there are no file reads or network requests at runtime. The same data works unchanged in Node.js, browsers, and frameworks like React and Next.js, without any configuration.

Development

data/US.txt (GeoNames) is the source of truth. data/zip-data.js is generated from it and is not committed.

npm ci            # installs and runs the build (generates data/zip-data.js, then bundles)
npm test
npm run process-data   # regenerate data/zip-data.js after editing data/US.txt

Related Projects

Looking for Indian postal codes? Check out postalcodes-india - the same functionality for India! 🇮🇳

Data Source

This package uses GeoNames ZIP code data (under Creative Commons Attribution 4.0 License).

License

MIT