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.result.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['result']['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.result.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['result']['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>();
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['matched'], r['matches'][0]['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