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.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/address?address=350+fifth+ave+new+york+10118"
const resp = await fetch(
  'https://api.zip-codes.com/v2/address?address=350+fifth+ave+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 fifth ave 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+fifth+ave+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=400+brod+street+seatle+washington"
const resp = await fetch(
  'https://api.zip-codes.com/v2/address?address=400+brod+street+seatle+washington',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
console.log(data.results[0].data.formatted_address);
// "400 BROAD ST, SEATTLE, WA 98109-4607"
import requests

resp = requests.get('https://api.zip-codes.com/v2/address',
    params={'address': '400 brod street seatle washington'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
# 400 BROAD ST, SEATTLE, WA 98109-4607
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=400+brod+street+seatle+washington");
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 or low)
correction What was changed in your input ZIP_CORRECTED · CITY_CORRECTED · STATE_CORRECTED · HOUSE_NUMBER_CORRECTED · STREET_CORRECTED
warning Something that may need your attention NO_HOUSE_NUMBER · SECONDARY_NEEDED · SECONDARY_NOT_VERIFIED · INPUT_NOT_USED · ZIP4_WITHHELD
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 other infromation.

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[0].matches.forEach(m => console.log(m.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 m in data['results'][0]['matches']:
    print(m['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[0].matches.forEach(m => console.log(m.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 m in data['results'][0]['matches']:
    print(m['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[0].matches.forEach(m => console.log(m.name, m.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 m in data['results'][0]['matches']:
    print(m['name'], m['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].matches[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,cd,acs_demographic"
const resp = await fetch(
  'https://api.zip-codes.com/v2/zip?code=90210&include=timezone,census,cd,acs_demographic',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await resp.json();
const pop = data.results[0].acs.current.demographic.sex_and_age.total_population.est;
console.log(`Population: ${pop}`); // "Population: 19004"
import requests

resp = requests.get('https://api.zip-codes.com/v2/zip',
    params={'code': '90210', 'include': 'timezone,census,cd,acs_demographic'},
    headers={'X-API-Key': 'YOUR_API_KEY'})
data = resp.json()
pop = data['results'][0]['acs']['current']['demographic']['sex_and_age']['total_population']['est']
print(f'Population: {pop}')  # Population: 19004
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,cd,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.3 mi / 3948.15 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.3 mi / 3948.15 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); // "Toronto"
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'])  # 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=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