API Reference

Documentation for the PostalDataPI API endpoints. Built in the USA, serving 70+ countries worldwide.

Base URL

https://postaldatapi.com/api

SDKs

Get started quickly with official client libraries:

Python

pip install postaldatapi

from postaldatapi import PostalDataPI

client = PostalDataPI(api_key="YOUR_API_KEY")
result = client.lookup("90210")

Node.js

npm install postaldatapi

import { PostalDataPI } from "postaldatapi";

const client = new PostalDataPI({ apiKey: "YOUR_API_KEY" });
const result = await client.lookup("90210");

Authentication

Every request must include your API key in the apiKey field of the JSON request body.

Country Parameter

All endpoints accept an optional country parameter — an ISO 3166-1 alpha-2 code (e.g., "US", "DE", "GB", "JP"). Defaults to "US" if omitted.

Endpoints

POST /api/lookup

Returns city and state/region for a postal code.

Request (US)

{
  "zipcode": "90210",
  "apiKey": "YOUR_API_KEY"
}

Request (Germany)

{
  "zipcode": "10115",
  "country": "DE",
  "apiKey": "YOUR_API_KEY"
}

Response

{
  "city": "Beverly Hills",
  "state": "California",
  "ST": "CA"
}

Errors: 400 (missing/invalid), 401 (unauthorized), 404 (not found), 429 (rate limit)

POST /api/city

Returns a list of postal codes for a given city. For US queries, state or ST is required.

Request (US)

{
  "city": "Beverly Hills",
  "ST": "CA",
  "apiKey": "YOUR_API_KEY"
}

Request (Germany)

{
  "city": "Berlin",
  "country": "DE",
  "apiKey": "YOUR_API_KEY"
}

Response

{
  "zipcodes": ["90209", "90210", "90211", "90212", "90213"]
}

Errors: 400 (missing/invalid), 404 (not found)

POST /api/validate

Checks if a postal code exists. Returns { "valid": true } or { "valid": false }.

Request (US)

{
  "zipcode": "90210",
  "apiKey": "YOUR_API_KEY"
}

Request (UK)

{
  "zipcode": "SW1A",
  "country": "GB",
  "apiKey": "YOUR_API_KEY"
}

Response

{
  "valid": true,
  "zipcode": "90210"
}

Errors: 400 (missing/invalid), 401 (unauthorized)

POST /api/metazip

Returns all available metadata for a postal code (coordinates, county, timezone, and more).

Request

{
  "zipcode": "90210",
  "apiKey": "YOUR_API_KEY"
}

Response (US)

{
  "meta": {
    "zipcode": "90210",
    "city": "Beverly Hills",
    "state": "California",
    "stateAbbrev": "CA",
    "county": "Los Angeles County",
    "latitude": 34.1031,
    "longitude": -118.4163,
    "timezone": "America/Los_Angeles"
  }
}

Errors: 400 (missing/invalid), 404 (not found)

POST /api/aboutapi

Returns API version, coverage, and usage information.

Request

{
  "apiKey": "YOUR_API_KEY"
}

Errors: 400 (missing apiKey), 401 (invalid apiKey)

Error Codes

Status	Meaning
400	Missing or invalid parameters
401	Invalid API key
402	Insufficient balance
404	Postal code or city not found
429	Rate limit exceeded
500	Internal server error