ZIP Code API mapping visualization

ZIP Code API Technical Reference

Everything you need to integrate U.S. and Canadian ZIP/Postal Code data. Fast reference for 8 API endpoints serving 41,000+ U.S. ZIP Codes and 892,000+ Canadian Postal Codes. RESTful design, simple authentication, comprehensive schemas, and credit-based access with no rate limits.

8 REST Endpoints
~60ms Response Time
No Rate Limits
HTTPS/TLS Encrypted
Read Documentation Try API Playground

At-a-Glance Specifications

Quick overview of API capabilities, coverage, and performance metrics

API Basics
  • Base URL: https://api.zip-codes.com/ZipCodesAPI.svc/1.0
  • Protocol: HTTPS Required
  • Authentication: API Key (querystring)
  • Response Formats: JSON (default), XML
  • CORS: Enabled
Coverage
  • U.S. ZIP Codes: 41,000+ active
  • Canadian Postal Codes: 892,000+ active
  • Coverage: U.S. + Canada (complete)
  • Updates: Monthly (1st of month)
  • Accuracy: 99.9%
Performance
  • Quick Endpoints: ~60ms avg
  • Full Endpoints: ~500ms avg
  • Rate Limits: None (credit-based)
  • Concurrency: Unlimited
  • Timeout: 30 seconds
Reliability
  • Uptime SLA: 99.9% monthly
  • Data Accuracy: 99.9% guaranteed
  • Support Response: <24 hours
  • Monitoring: Real-time (Uptime Robot)
  • Maintenance: 7-day advance notice

Endpoints Overview

Endpoint Path Credits Response Time Description
QuickGetZipCodeDetails /1.0/QuickGetZipCodeDetails/{zipcode} 1 ~60ms Returns city, state, county, latitude, longitude, and timezone for a ZIP code
GetZipCodeDetails /1.0/GetZipCodeDetails/{zipcode} 1 ~500ms Returns complete location and demographic data including 60+ fields (population, income, housing, employment statistics)
GetCreditInfo /1.0/GetCreditInfo 0 ~60ms Reports current credit usage, remaining credits, total allotment, and reset date for account monitoring
FindZipCodesInRadius /1.0/FindZipCodesInRadius 1 ~500ms Lists all ZIP codes within a specified radius of a given ZIP code (mile-based, Haversine distance)
FindZipCodesInRadiusByLatLon /1.0/FindZipCodesInRadiusByLatLon 1 ~500ms Lists all ZIP codes within a specified radius of given latitude/longitude coordinates
CalculateDistanceByZip /1.0/CalculateDistanceByZip 1 ~60ms Calculates straight-line distance in miles between two ZIP codes using Haversine formula
CalculateDistance /1.0/CalculateDistance 1 ~60ms Calculates straight-line distance in miles between two lat/lon coordinate pairs
GetAllZipCodes /1.0/GetAllZipCodes 1 ~500ms Lists all ZIP codes by state/province or country (requires state parameter for filtering)

For detailed implementation guides, code examples in 5 languages, and complete parameter documentation:

View Full Documentation

Authentication & Security

Authentication Method

  • Method: Simple API Key authentication
  • Parameter: key (querystring, not header)
  • Format: Append ?key=YOUR_API_KEY to all requests
  • Required: Yes, for every endpoint
  • Multiple keys: Not supported (single key per account)

Example Request:

GET https://api.zip-codes.com/ZipCodesAPI.svc/1.0/QuickGetZipCodeDetails/90210?key=YOUR_API_KEY

Key Management

  • One key per account (multi-key support: roadmap)
  • Storage: Use environment variables, never hardcode in source
  • Exposure: User responsible for key protection
  • If compromised: Contact support immediately for instant regeneration
  • Key rotation: Not currently supported (manual regeneration only)
  • Client-side warning: Avoid exposing keys in browser code (use server-side proxy)

Security Standards

  • Encryption: HTTPS required (TLS encrypted)
  • HTTP Support: None - HTTP requests automatically redirect to HTTPS
  • Certificate: Valid SSL certificate installed
  • Data Protection: All API traffic encrypted in transit

CORS & Client-Side Use

  • Browser JavaScript: Fully supported (CORS enabled)
  • Server-Side: Recommended for API key protection
  • Mobile Apps: Native iOS/Android supported
  • Static Sites: Works with JAMstack, GitHub Pages, etc.
Note: CORS allows browser-based API calls. For production apps, consider server-side proxy to protect API key.

IP Restrictions

  • Whitelisting: Not supported
  • IP logging: For support/debugging only
  • Geofencing: Not available

Response Schemas

Complete field definitions for each endpoint response

ZIP Lookup Schemas

QuickGetZipCodeDetails

Returns 7 essential fields for fast ZIP code lookup

{
  "ZipCode": "90210",
  "City": "Beverly Hills",
  "State": "CA",
  "County": "Los Angeles",
  "Latitude": 34.103131,
  "Longitude": -118.416253
}
<QuickGetZipCodeDetailsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ZipCode>90210</ZipCode>
  <City>Beverly Hills</City>
  <State>CA</State>
  <County>Los Angeles</County>
  <Latitude>34.103131</Latitude>
  <Longitude>-118.416253</Longitude>
</QuickGetZipCodeDetailsResult>
Field Definitions
Field Type Description Example
ZipCode string Five-digit ZIP code "90210"
City string City name (USPS standard) "Beverly Hills"
State string Two-letter state abbreviation "CA"
County string County name "Los Angeles"
Latitude number Decimal degrees (WGS84, 6 places) 34.103131
Longitude number Decimal degrees (WGS84, 6 places) -118.416253

GetZipCodeDetails (60+ Fields)

Returns all QuickGet fields plus 80+ additional demographic, geographic, and statistical fields

Note: Demographic data from U.S. Census Bureau may lag 1-2 years due to Census cycle. Location data is always current.

Field Type Description Example
ZipCode string Five-digit ZIP code "90210"
City string City name (USPS uppercase format) "BEVERLY HILLS"
MixedCaseCity string City name (proper case) "Beverly Hills"
State string Two-letter state abbreviation "CA"
StateFullName string Full state name "California"
CountyName string County name (uppercase) "LOS ANGELES"
Latitude string Decimal degrees (WGS84) "34.103131"
Longitude string Decimal degrees (WGS84) "-118.416253"
Elevation string Elevation in feet "719.00"
TimeZone string Time zone offset (hours from UTC) "8"
DayLightSaving string Observes daylight saving (Y/N) "Y"
AreaCode string Area codes for ZIP (slash-separated) "310/323/424/738"
CountyFIPS string FIPS county code "037"
StateFIPS string FIPS state code "06"

Field Type Description Example
ZipCodePopulation string Total population for ZIP code "21134"
PopulationEstimate string Current population estimate "22933"
MalePop string Male population "10099"
FemalePop string Female population "11035"
WhitePop string White population "17130"
BlackPop string Black/African American population "366"
HispanicPop string Hispanic/Latino population "1296"
AsianPop string Asian population "1406"
IndianPop string Native American/Alaska Native population "25"
HawaiianPop string Native Hawaiian/Pacific Islander population "12"
OtherPop string Other race population "481"
MedianAge string Median age (years) "49.30"
MedianAgeMale string Median age for males (years) "49.30"
MedianAgeFemale string Median age for females (years) "49.20"
PersonsPerHousehold string Average persons per household "2.47"
AverageFamilySize string Average family size "3.13"

Field Type Description Example
HouseholdsPerZipcode string Total households in ZIP code "8553.0000"
AverageHouseValue string Average home value (USD) "2000000.00"
IncomePerHousehold string Average household income (USD) "190382.00"

Field Type Description Example
Bus03Establishments string Number of business establishments (2003 data) "2557"
Bus03Employment string Total employment (2003 data) "33505"
Bus03PayrollQuarter1 string Q1 payroll in $1000s (2003 data) "638801"
Bus03PayrollAnnual string Annual payroll in $1000s (2003 data) "2935275"
Bus03EmploymentFlag string Employment data flag " "
CBSADivPop2003 string CBSA Division population (2003) "9818605"

Field Type Description Example
DeliveryActive string Active delivery points "10623"
DeliveryBusiness string Business delivery points "1472"
DeliveryResidential string Residential delivery points "9285"
DeliverySpecial string Special delivery points "9285"
DeliveryBox string PO box delivery points "0"
DeliverySFDU string Single family dwelling units "6776"
DeliveryMFDU string Multi-family dwelling units "2418"

Field Type Description Example
AreaLand string Land area in square miles "10.748000"
AreaWater string Water area in square miles "0.054000"
Region string Census region "West"
Division string Census division "Pacific"

Field Type Description Example
MSA string Metropolitan Statistical Area code "4472"
MSAName string MSA name "Los Angeles-Riverside-Orange County, CA"
PMSA string Primary MSA code "4480"
PMSAName string PMSA name "Los Angeles-Long Beach, CA PMSA"
CSA string Combined Statistical Area code "348"
CSAName string CSA name "Los Angeles-Long Beach, CA"
CBSA string Core Based Statistical Area code "31080"
CBSA_Name string CBSA name "Los Angeles-Long Beach-Anaheim, CA"
CBSA_Type string CBSA type (Metro/Micro) "Metro"
CBSA_DIV string CBSA division code "31084"
CBSA_DIV_Name string CBSA division name "Los Angeles-Long Beach-Glendale, CA"

Field Type Description Example
SSA_State_County_Code string Social Security Administration state/county code "05200"
Medicare_CBSA_Code string Medicare CBSA code "31084"
Medicare_CBSA_Name string Medicare CBSA name "Los Angeles-Long Beach-Glendale, CA"
Medicare_Rating_Area_ID string Medicare rating area identifier "16"

Field Type Description Example
Primary string Primary ZIP indicator (P=Primary) "P"
CityType string City type code "P"
Classification string ZIP classification (blank=Standard, M=Military, P=PO Box, U=Unique) " "
CityAliasName string City alias name "BEVERLY HILLS"
MixedCaseAlias string City alias (proper case) "Beverly Hills"
MailingName string Valid mailing name indicator "Y"
MultiCounty string ZIP spans multiple counties indicator " "
Prev string Previous ZIP code in sequence "90209"
Next string Next ZIP code in sequence "90211"
CityStateKey string City/state key identifier "Z20259"
PreferredLastLineKey string Preferred last line key "Z20259"
PreferredLastLineName string Preferred city name for mailing "BEVERLY HILLS"
IntroDateZIP string ZIP introduction date "<2004-10"
FacilityCode string Post office facility code "P"
CityDeliveryIndicator string City delivery available (Y/N) "Y"
CarrierRouteRateSortation string Carrier route sortation indicator "D"
FinanceNumber string USPS finance number "050666"
UniqueZIPName string/null Name if unique ZIP (single building/org) null

Field Type Description Example
_109thDistrict string 109th Congressional District(s) "0"
_109thArea string 109th District area "0"
_110thDistrict string 110th Congressional District(s) (pipe-separated) "30|32|36"
_110thArea string 110th District areas (pipe-separated) "135.94|124.23|5912.64"
GrowthRank string Growth rank "0"
GrowthHousingUnits2003 string Housing units in 2003 "0"
GrowthHousingUnits2004 string Housing units in 2004 "0"
GrowthIncreaseNumber string Net increase in housing units "0"
GrowthIncreasePercentage string Percentage growth in housing "0.00"
CountiesArea string County area code "4060"

Field Type Description Example
ID string Internal database ID "73166"
CountyANSI string ANSI county code "037"
StateANSI string ANSI state code "06"
CityAliasType string/null City alias type null
CityAliasAbbr string/null City alias abbreviation null
AreaCodeTemp string Temporary area codes "310/323/424/738"
CountyMixedCase string/null County name (proper case) null

Utility Schemas

GetCreditInfo

Returns current credit usage and account status (0 credits)

Field Type Description Example
CreditsUsed integer Credits consumed this billing cycle 150
CreditsRemaining integer Credits remaining until reset 100
CreditsTotal integer Total monthly credit allotment 250
ResetDate string Next reset date (ISO 8601 format) "2025-12-15T00:00:00Z"
Additional Schemas: FindZipCodesInRadius, CalculateDistance, and GetAllZipCodes schemas follow similar patterns. See full documentation for complete endpoint details.

Error Handling & Status Codes

HTTP Status Codes

Status Codes Used:
  • 200 OK - Successful requests AND API-level errors (check response body)
  • 400 Bad Request - Malformed request (web server level)
  • 404 Not Found - Invalid endpoint path (web server level)
  • 503 Service Unavailable - Scheduled maintenance or server unavailable
Error Detection:
  • For 200 responses: Check for "Error" field in response body
  • For 4xx/5xx responses: Standard HTTP error (infrastructure issue)

Error Response Schema

{
  "Error": "Credit limit has been reached."
}
<Error xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Error>Credit limit has been reached.</Error>
</Error>

Error Messages by Category

Authentication Errors
Error Message Cause Resolution
Access is denied. Invalid or missing API key Verify key in account dashboard
User Key is required. Missing key parameter in request Add ?key=YOUR_API_KEY to URL
Credit/Limit Errors
Error Message Cause Resolution
Credit limit has been reached. Monthly credits exhausted Upgrade plan or wait for reset on billing anniversary
Input Validation Errors
Error Message Cause Resolution
Invalid ZIP Code. ZIP doesn't exist or is inactive Verify ZIP is active 5-digit code
Invalid ZIP Code or Postal Code. Invalid format for U.S. or Canadian code Check format: 12345 (US) or A1A 1A1 (Canada)
Invalid Minimum Radius. Minimum radius parameter invalid Use numeric value >= 0
Invalid Maximum Radius. Maximum radius parameter invalid Use numeric value <= 500 miles
Maximum radius must be greater than the Minimum Radius. Max radius less than min radius Ensure maximumradius > minimumradius
Invalid Latitude/Longitude. Invalid coordinate format Use decimal degrees: -90 to 90 (lat), -180 to 180 (lon)
Invalid Latitude. Latitude out of range Latitude must be -90 to 90
Invalid Longitude. Longitude out of range Longitude must be -180 to 180
Country is required. Missing country parameter Add country=US or country=CA
Invalid State/Province. Invalid state code Use 2-letter state/province code
Invalid City. City name not found Verify city name spelling
Invalid State. State code not found Use valid 2-letter state code
Address, City, and State are required. Missing required address parameters Provide all three parameters
Server/System Errors
Error Message Cause Resolution
Server error. Internal server error Retry request; contact support if persistent
Error Connecting to USPS Server. Upstream USPS connection issue Temporary issue; retry after brief delay

Data Standards & Formats

Geographic Coordinates

  • Format: Decimal degrees (e.g., 34.103131, -118.416253)
  • Precision: 6 decimal places (~4 inch accuracy)
  • Range: Latitude -90 to 90, Longitude -180 to 180
  • Coordinate System: WGS84 (EPSG:4326) - standard GPS datum

Time Zone Codes

Custom numeric system (legacy format). Use the IANA equivalents column for modern timezone handling.

Code Time Zone Name IANA Equivalent
4 Atlantic Standard Time America/Halifax
5 Eastern Standard Time America/New_York
6 Central Standard Time America/Chicago
7 Mountain Standard Time America/Denver
8 Pacific Standard Time America/Los_Angeles
9 Alaska Standard Time America/Anchorage
10 Hawaii-Aleutian Standard Time Pacific/Honolulu
11 Samoa Standard Time Pacific/Pago_Pago
13 Chamorro Standard Time (Guam) Pacific/Guam

Note: IANA equivalents are approximate - multiple IANA zones may map to single code.

Distance Calculations

  • Formula: Haversine (great-circle distance)
  • Method: "As-the-crow-flies" straight-line distance
  • Unit: Miles (statute miles)
  • Note: Does not account for driving routes or terrain

ZIP/Postal Code Formats

U.S. ZIP Codes:
  • Format: 5 digits (e.g., 90210)
  • ZIP+4: Not supported - omit last 4 digits if present
  • Leading Zeros: Preserve (e.g., 01234 not 1234)
Canadian Postal Codes:
  • Format: A1A 1A1 (letter-digit-letter space digit-letter-digit)
  • Example: M5H 2N2 (Toronto)
  • Space: Optional in queries (M5H2N2 or M5H 2N2 both accepted)
  • Case: Case-insensitive
Validation: All codes must match active codes only - retired/decommissioned codes return error.

Output Formats

Response Formats:
  • JSON (default): https://api.zip-codes.com/.../QuickGetZipCodeDetails/90210
  • XML: https://api.zip-codes.com/.../XML/QuickGetZipCodeDetails/90210
Format Specifications:
  • Character Encoding: UTF-8
  • Field Selection: Not available (full schema returned)
  • Response Compression: Supported (gzip, deflate, br, zstd)

Performance & Limits

Response Times

Server-side processing time (95th percentile). Times exclude network latency and client processing.

Endpoint Type Response Time Examples
Quick Lookups ~60ms QuickGetZipCodeDetails, GetCreditInfo
Distance Calculations ~60ms CalculateDistance, CalculateDistanceByZip
Full Data ~500ms GetZipCodeDetails
Radius Searches ~500ms FindZipCodesInRadius, FindZipCodesInRadiusByLatLon
Bulk Operations ~500ms+ GetAllZipCodes (varies by result size)

Rate Limits

  • Rate Limits: None
  • Throttling: None
  • Credit System: 1 request = 1 credit (limit based on monthly allotment, not requests/second)
  • Concurrency: Unlimited simultaneous requests

Request Limits

  • Max URL length: 2,048 characters (browser standard)
  • Max radius search: 500 miles (practical limit)
  • Timeout: 30 seconds (server-side)
  • Payload size: N/A (GET requests only)

Concurrency

  • Simultaneous requests: Unlimited
  • Recommended: Based on your infrastructure capacity
  • No queue system: Immediate processing

Data Coverage & Updates

United States Coverage

  • Active ZIP Codes: 41,000+
  • States: All 50 states + DC
  • Territories: Puerto Rico, Virgin Islands, Guam, American Samoa, Northern Mariana Islands
  • Military: Complete worldwide APO/FPO/DPO coverage
  • Special Codes: PO Box detection, Unique ZIP flagging

Canadian Coverage

  • Active Postal Codes: 892,000+
  • Provinces: All 10 provinces
  • Territories: Yukon, Northwest Territories, Nunavut
  • Format: Complete FSA (Forward Sortation Area) and LDU (Local Delivery Unit)
  • Data Source: Licensed Canada Post data

Update Schedule

Update Schedule:
  • Frequency: Monthly, on the 1st of each month
  • Update Window: 12:00 AM - 2:00 AM EST
  • Downtime: Typically none (live updates)
  • Changes: New ZIP codes, decommissioned codes, boundary updates, demographic refreshes
Data Sources:
  • U.S. ZIP Codes: USPS (licensed monthly feed)
  • Canadian Postal Codes: Canada Post (licensed monthly feed)
  • Demographics: U.S. Census Bureau, Statistics Canada (annual updates)
Note: Demographic data may lag 1-2 years due to Census cycle. Location data (city, state, lat/lon, county) is always current and updated monthly from USPS.

Data Accuracy

  • Guarantee: 99.9% accurate
  • Active codes only: No retired/decommissioned ZIPs
  • Validation: Against official USPS/Canada Post databases
  • History: 23 years of continuous monthly updates

Data Sources

  • U.S. Postal Service (USPS) - Licensed
  • Canada Post - Licensed
  • U.S. Census Bureau - Public data
  • Statistics Canada - Public data
  • USGS (coordinates) - Public data
  • CMS (medical demographics) - Public data

Ready to Get Started?

Start your free tier with 250 lookups every month. No credit card required.

Start Free View Pricing Documentation

Join 10,000+ developers using our API

4.9/5 Rating 99.9% Uptime 23 Years Trusted