Loading
Loading
Retrieve all ZIP or postal codes for a given city and country. Optionally narrow results by providing a state or province name. Results are paginated with up to 500 codes per page.
Supports global postal data. Use state_name to improve accuracy when cities share names across states.
Pass your API key as the apiKey parameter in every request.
This is version v1.0 of the API.
city and country are required. Use page to paginate results when more than 500 codes exist.
cityrequiredstringName of the city whose ZIP codes you want to search.
countryrequiredstringCountry where the city exists. Must be in ISO 3166-1 alpha-2 format.
state_nameoptionalstringState, region, or province of the city. Optional but recommended to improve accuracy.
pageoptionalintegerdefault: 1Page number for paginated results (up to 500 codes per page). Must be greater than 0.
formatoptionalstringdefault: jsonResponse format: 'json' (default) or 'xml'.
Returns 200 OK with pagination metadata and a codes array of ZIP code strings.
total_resultsTotal number of ZIP codes found.
total_pagesTotal number of pages. Each page contains up to 500 results.
current_pageCurrent page number.
current_page_sizeNumber of ZIP codes returned in this page.
codesArray of ZIP codes or postal code strings for the queried location.
The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.
Only ISO 3166-1 alpha-2 codes country codes are supported.
The page number must be greater than 0.
No postal/zip codes found for the provided city XYZNOTACITY in country US.
The requested page exceeds the available page range.