US Zip Code API

API Documentation

The US Zip Code API is the easiest way to look up US zip codes by zip, city, state, or coordinates, with county names and full 5-digit county FIPS codes on every record.

Please see the official API documentation on RapidAPI for the complete, up-to-date specification, including response formats and pricing plans.

Overview

The US Zip Code API is a fast lookup service for 41,000+ US zip codes. Every record includes the city, state, county, full 5-digit county FIPS code, and coordinates, in the same JSON shape on every endpoint. It is hosted on RapidAPI, and allows for different calls to be made based on what your needs are.

The API is perfect for the following use cases:

  • Checkout and signup forms that autofill city and state from a zip
  • Validating shipping addresses before they reach a fulfillment system
  • “Find a store / provider / agent near you” searches
  • Delivery-zone and service-area checks
  • Joining records to Census, BLS, CDC, or USDA data by county FIPS code
  • Tagging GPS coordinates from a mobile app with a zip code

Key Features

  • Full County FIPS: Every record has the 5-digit county code that government datasets are keyed on, not just a county name
  • Zip Lookup: Look up a single zip, or up to 100 at a time
  • City and State Search: Find every zip code in a city, a state, or both
  • Radius Search: Find every zip code within 1–500 miles of a zip, closest first
  • Reverse Geocoding: Find the zip code closest to a latitude and longitude
  • Fast and Predictable: The whole dataset lives in memory, so lookups take milliseconds, and every endpoint returns the same record shape

Getting Started

Requests go through RapidAPI, so every call needs your RapidAPI key. Subscribe to the API on RapidAPI to get one, then send it with each request:

Terminal window
curl "https://us-zip-code-api1.p.rapidapi.com/zip/90210" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: us-zip-code-api1.p.rapidapi.com"

Every endpoint returns records in the same shape:

Response
{
  "zip": "90210",
  "city": "Beverly Hills",
  "state": "CA",
  "state_name": "California",
  "county": "Los Angeles",
  "county_fips": "06037",
  "lat": 34.0901,
  "lng": -118.4065
}

/nearby and /nearest add distance_miles (rounded to 0.1 mile) to each record.

Errors are always JSON with a single message, like { "error": "message" }. A 400 means a parameter is missing or invalid (for example, non-numeric miles, more than 100 zips, or out-of-range coordinates), and the message says which. A 404 means the zip (for /zip) or origin zip (for /nearby) doesn’t exist.

Endpoints

Look Up a Zip Code

GET /zip/{zip}

Looks up a single zip code. Keep leading zeros (02134, not 2134).

Example:

GET /zip/90210

Look Up Multiple Zip Codes

GET /zips?zips={zip1,zip2,...}

Looks up to 100 zip codes at a time, separated by commas. Zips that don’t exist are skipped rather than causing an error, so match results back to your input by the zip field.

Example:

GET /zips?zips=10001,60614,94105

Search by City and State

GET /search?city={city}&state={state}

Finds zip codes by city, state, or both. The city is a case-insensitive partial match (Springfield also matches West Springfield); the state is a 2-letter code. Returns at most 500 records.

Example:

GET /search?city=Springfield&state=IL

Find Nearby Zip Codes

GET /nearby?zip={zip}&miles={miles}

Finds every zip code within 1–500 miles of a zip, closest first, with the distance in miles. Returns at most the 500 closest zips.

Example:

GET /nearby?zip=80202&miles=10

Find the Nearest Zip Code

GET /nearest?lat={lat}&lng={lng}

Finds the zip code closest to a coordinate (reverse geocoding). Latitude is −90 to 90 and longitude is −180 to 180.

Example:

GET /nearest?lat=40.7484&lng=-73.9857

Data Notes

  • Coverage: All 50 states, DC, and military APO/FPO zips (about 41,500 zip codes). Puerto Rico, Guam, and the US Virgin Islands are not included
  • Military zips (APO/FPO) have an empty state, state_name, and county, and a null county_fips
  • Coordinates are each zip’s approximate center, not a boundary. /nearest returns the zip whose center is closest to your point, so near a zip boundary it can return the neighboring zip
  • Distances are straight-line (“as the crow flies”), not driving distance
  • Updates: The dataset is refreshed periodically; zip codes change rarely

Postal code data from GeoNames, licensed under CC BY 4.0.

Support

Please contact us with any issues you are having by emailing us at support@moonlabs.app. If there is a feature you’d like us to add, please let us know!