ZIP-Codes.com
| 800-425-1169

Code Samples

Copy-paste examples for common use cases. Four languages, real responses.

Address Address Batch Suggest Store Locator Autofill Intelligence Distance Canadian Batch

Address Validation

GET /v2/address

Throw any address at it — messy, misspelled, missing punctuation, all lowercase. No structured fields needed. Just one string, however a human actually writes it, and get back a standardized USPS-validated address with ZIP+4.

The USPS retired their Web Tools API platform on January 25, 2026. The replacement USPS APIs at developers.usps.com impose a default limit of 60 requests per hour — with no self-serve path to increase it. Our /address endpoint has no such restriction.

Beta 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/address?address=350+fifthave+new+york+10118"
const resp = await fetch(
  'https://api.zip-codes.com/v2/address?address=350+fifthave+new+york+10118',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].data.formatted_address); // "350 5TH AVE, NEW YORK, NY 10118-0110"
import requests

resp = requests.get('https://api.zip-codes.com/v2/address',
    params={'address': '350 fifthave new york 10118'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
print(data['results'][0]['data']['formatted_address'])  # 350 5TH AVE, NEW YORK, NY 10118-0110
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/address?address=350+fifthave+new+york+10118");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
No structured fields needed. Just one address parameter with however a human actually types it — typos, missing commas, no ZIP, wrong state. The parser handles it all. 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/address?address=123+martin+luthr+kng+blvd+ste+4+orlando+flordia"
const resp = await fetch(
  'https://api.zip-codes.com/v2/address?address=123+martin+luthr+kng+blvd+ste+4+orlando+flordia',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].data.formatted_address);
// "123 MARTIN LUTHER KING JR BLVD STE 4, ORLANDO, FL 32801-1234"
import requests

resp = requests.get('https://api.zip-codes.com/v2/address',
    params={'address': '123 martin luthr kng blvd ste 4 orlando flordia'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
# 123 MARTIN LUTHER KING JR BLVD STE 4, ORLANDO, FL 32801-1234
print(data['results'][0]['data']['formatted_address'])
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/address?address=123+martin+luthr+kng+blvd+ste+4+orlando+flordia");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Built-in input cleaning. Before matching, the parser automatically handles:
  • Email addresses and phone numbers — stripped automatically if accidentally included
  • Accented and Unicode characters — normalized to ASCII equivalents (café → cafe)
  • Pipe-delimited input — 123 Main St | Chicago | IL works just like commas
  • URL-encoded strings — %20, + signs, and percent-encoding decoded automatically
  • Recipient and attention lines — names, ATTN:, C/O lines stripped before matching
  • Misspellings — phonetic and fuzzy matching corrects common typos in street names, cities, and states
  • Missing punctuation — no commas, no ZIP, no state? The parser infers structure from city lookup
Input requirements. For best results, include at least a street address with city + state or a ZIP code.
  • Best: Street + City + State + ZIP — fastest, most accurate
  • Good: Street + City + State (no ZIP) — we find the right ZIP
  • Good: Street + ZIP (no city/state) — ZIP is the primary lookup key
  • Works: Street + City (no state, no ZIP) — works when the city name is unambiguous
  • Won't work: Street + State only — too many possible cities to match reliably

Response Notices

Every successful result includes a notices array. Each notice has a code, message, and class.

ClassMeaningCodes
match How the address was resolved (exactly 1 per result) MATCHED (high) · PARTIAL_MATCH (medium) · DEFAULT_MATCH (medium) · AMBIGUOUS (low)
correction What was changed in your input ZIP_CORRECTED · CITY_CORRECTED · SUFFIX_CHANGED · SUFFIX_REMOVED · DIRECTIONAL_CHANGED
warning Something that may need your attention SECONDARY_NOT_VERIFIED · SECONDARY_NEEDED · SECONDARY_INVALID · SECONDARY_NEEDS_NUMBER
info Informational context PO_BOX_STREET_ADDRESS · UNIQUE_ZIP · MILITARY_ADDRESS · GENERAL_DELIVERY
About delivery validation. This endpoint validates addresses against USPS ZIP+4 delivery records and returns standardized components, ZIP+4 codes, and delivery metadata. A successful match confirms the address exists in USPS records. Delivery Point Validation (DPV), which confirms an address is currently receiving mail, is on our roadmap.
Try it live

Address Batch

POST /v2/address/batch

Validate and standardize up to 100 addresses in a single call. Returns ZIP+4 append, formatted addresses, and optional coordinates.

Requires Developer plan or above 
curl -X POST https://api.zip-codes.com/v2/address/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["350 5th Ave, New York, NY 10118","1600 Pennsylvania Ave NW, Washington, DC 20500","233 S Wacker Dr, Chicago, IL 60606"]}'
const resp = await fetch('https://api.zip-codes.com/v2/address/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: [
      '350 5th Ave, New York, NY 10118',
      '1600 Pennsylvania Ave NW, Washington, DC 20500',
      '233 S Wacker Dr, Chicago, IL 60606'
    ]
  })
});
const data = await resp.json();
console.log(data.results.length); // 3
import requests

resp = requests.post('https://api.zip-codes.com/v2/address/batch',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'addresses': [
            '350 5th Ave, New York, NY 10118',
            '1600 Pennsylvania Ave NW, Washington, DC 20500',
            '233 S Wacker Dr, Chicago, IL 60606'
        ]
    })
data = resp.json()
for r in data['results']:
    print(r['data']['formatted_address'])
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var body = JsonContent.Create(new {
    addresses = new[] {
        "350 5th Ave, New York, NY 10118",
        "1600 Pennsylvania Ave NW, Washington, DC 20500",
        "233 S Wacker Dr, Chicago, IL 60606"
    }
});
var resp = await client.PostAsync(
    "https://api.zip-codes.com/v2/address/batch", body);
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();

Smart Autocomplete

GET /v2/suggest

Add instant typeahead to any input — ZIP codes, cities, counties, school districts, or Canadian postal codes. Fuzzy matching handles misspellings. Proximity bias ranks nearby results higher. Returns coordinates and bounding boxes for map integration.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=beverly&limit=5&include=zip,place"
const resp = await fetch(
  'https://api.zip-codes.com/v2/suggest?q=beverly&limit=5&include=zip,place',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
data.results.forEach(r => console.log(r.name));
import requests

resp = requests.get('https://api.zip-codes.com/v2/suggest',
    params={'q': 'beverly', 'limit': '5', 'include': 'zip,place'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
for r in data['results']:
    print(r['name'])
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/suggest?q=beverly&limit=5&include=zip,place");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();

ZIP Code Typeahead

User starts typing a ZIP — return only ZIP results. Perfect for checkout forms where you just need the code.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=9021&include=zip&limit=5"
const resp = await fetch(
  'https://api.zip-codes.com/v2/suggest?q=9021&include=zip&limit=5',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
data.results.forEach(r => console.log(r.name));
import requests

resp = requests.get('https://api.zip-codes.com/v2/suggest',
    params={'q': '9021', 'include': 'zip', 'limit': '5'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
for r in data['results']:
    print(r['name'])
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/suggest?q=9021&include=zip&limit=5");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();

City Search with Proximity Bias

Search for cities and boost results near a location. Pass a ZIP, coordinates, or “auto” to use the caller’s IP.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=spring&include=place&proximity=32504&limit=5"
const resp = await fetch(
  'https://api.zip-codes.com/v2/suggest?q=spring&include=place&proximity=32504&limit=5',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
data.results.forEach(r => console.log(r.name, r.state));
import requests

resp = requests.get('https://api.zip-codes.com/v2/suggest',
    params={'q': 'spring', 'include': 'place', 'proximity': '32504', 'limit': '5'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
for r in data['results']:
    print(r['name'], r['state'])
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/suggest?q=spring&include=place&proximity=32504&limit=5");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();

Map Integration

Every result includes coordinates and bounding boxes. Use them to drop pins, auto-fit map viewport, or calculate service areas — no second API call needed.

// Search as user types, auto-fit map to selection
const resp = await fetch(
  'https://api.zip-codes.com/v2/suggest?q=dupage+county&include=county&limit=1',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { results } = await resp.json();
const match = results[0];

// Drop a pin at the centroid
map.addMarker(match.location.lat, match.location.lon);

// Auto-fit the viewport to the bounding box
map.fitBounds([
  [match.bbox.min_lat, match.bbox.min_lon],
  [match.bbox.max_lat, match.bbox.max_lon]
]);
Fuzzy matching built in. Type “san fran”, “bev hils”, or “sprigfield” — the engine corrects typos automatically. Nine entity types: ZIP, place, county, CBSA, state, school district, FSA, Canadian postal, and USPS city.
Try it live

Store Locator / Find Nearby

GET /v2/radius

Find all ZIP codes within a radius. Power “find near me” features and service area lookups.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/radius?code=90210&max=25&include=timezone"
const resp = await fetch(
  'https://api.zip-codes.com/v2/radius?code=90210&max=25&include=timezone',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
const matches = data.results[0].matches;
console.log(`Found ${matches.length} ZIP codes within 25 miles`);
import requests

resp = requests.get('https://api.zip-codes.com/v2/radius',
    params={'code': '90210', 'max': '25', 'include': 'timezone'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
matches = data['results'][0]['matches']
print(f'Found {len(matches)} ZIP codes within 25 miles')
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/radius?code=90210&max=25&include=timezone");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Try it live

Address Form Autofill

GET /v2/quick-zip

Auto-fill city, state, and county from a ZIP code. Cut checkout form fields and reduce drop-off.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/quick-zip?code=90210&include=timezone"
const resp = await fetch(
  'https://api.zip-codes.com/v2/quick-zip?code=90210&include=timezone',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].city); // "Beverly Hills"
import requests

resp = requests.get('https://api.zip-codes.com/v2/quick-zip',
    params={'code': '90210', 'include': 'timezone'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
print(data['results'][0]['city'])  # Beverly Hills
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/quick-zip?code=90210&include=timezone");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Try it live

Location Intelligence

GET /v2/zip

Get complete location data: demographics, census boundaries, congressional districts, and timezone.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/zip?code=90210&include=timezone,census,acs_demographic"
const resp = await fetch(
  'https://api.zip-codes.com/v2/zip?code=90210&include=timezone,census,acs_demographic',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
const pop = data.results[0].demographics.population.total;
console.log(`Population: ${pop}`); // "Population: 21134"
import requests

resp = requests.get('https://api.zip-codes.com/v2/zip',
    params={'code': '90210', 'include': 'timezone,census,acs_demographic'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
pop = data['results'][0]['demographics']['population']['total']
print(f'Population: {pop}')  # Population: 21134
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/zip?code=90210&include=timezone,census,acs_demographic");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Try it live

Distance Calculator

GET /v2/distance

Calculate point-to-point distances for shipping estimates, logistics, or service area rules.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/distance?from=90210&to=10001"
const resp = await fetch(
  'https://api.zip-codes.com/v2/distance?from=90210&to=10001',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
const d = data.results[0].distance;
console.log(`${d.miles} mi / ${d.km} km`); // "2453.39 mi / 3948.3 km"
import requests

resp = requests.get('https://api.zip-codes.com/v2/distance',
    params={'from': '90210', 'to': '10001'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
d = data['results'][0]['distance']
print(f"{d['miles']} mi / {d['km']} km")  # 2453.39 mi / 3948.3 km
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/distance?from=90210&to=10001");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Try it live

Canadian Postal Codes

GET /v2/quick-zip

Full support for Canadian FSA and 6-digit postal codes. Same API, same response format.

FSA Lookup (3-character)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/quick-zip?code=M5V&include=timezone"
const resp = await fetch(
  'https://api.zip-codes.com/v2/quick-zip?code=M5V&include=timezone',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].city); // "Toronto"
import requests

resp = requests.get('https://api.zip-codes.com/v2/quick-zip',
    params={'code': 'M5V', 'include': 'timezone'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
print(data['results'][0]['city'])  # Toronto
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/quick-zip?code=M5V&include=timezone");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Full Postal Code (6-character)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/quick-zip?code=M1R0E9&include=timezone"
const resp = await fetch(
  'https://api.zip-codes.com/v2/quick-zip?code=M1R0E9&include=timezone',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].municipality); // "Scarborough"
import requests

resp = requests.get('https://api.zip-codes.com/v2/quick-zip',
    params={'code': 'M1R0E9', 'include': 'timezone'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
print(data['results'][0]['municipality'])  # Scarborough
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var resp = await client.GetAsync(
    "https://api.zip-codes.com/v2/quick-zip?code=M1R0E9&include=timezone");
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();
Try it live

Batch Processing

POST /v2/quick-zip/batch

Process up to 100 items in a single API call. Mix US and Canadian codes freely.

Requires Developer plan or above 
curl -X POST https://api.zip-codes.com/v2/quick-zip/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes":["90210","10001","M5V"],"include":["timezone"]}'
const resp = await fetch('https://api.zip-codes.com/v2/quick-zip/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    codes: ['90210', '10001', 'M5V'],
    include: ['timezone']
  })
});
const data = await resp.json();
console.log(data.results.length); // 3
import requests

resp = requests.post('https://api.zip-codes.com/v2/quick-zip/batch',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'codes': ['90210', '10001', 'M5V'],
        'include': ['timezone']
    })
data = resp.json()
print(len(data['results']))  # 3
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var body = JsonContent.Create(new {
    codes = new[] { "90210", "10001", "M5V" },
    include = new[] { "timezone" }
});
var resp = await client.PostAsync(
    "https://api.zip-codes.com/v2/quick-zip/batch", body);
var data = await resp.Content.ReadFromJsonAsync<JsonDocument>();

Ready to get started?

Sign up for free and start making API calls in minutes. No credit card required.

Sign Up Free View Pricing