Loading
Loading
Find all ZIP or postal codes within a specified radius of a central point. The central point can be a ZIP code + country or raw latitude/longitude coordinates. Results are sorted by distance from the center, paginated up to 500 per page.
Maximum radius: 100 km or 100 miles. Six distance units supported: km (default), mi, yd, m, ft, in. Results include city, region, district, and distance from center for each code.
Pass your API key as the apiKey parameter in every request.
This is version v1.0 of the API.
radius is required. Provide either code + country or lat/long as the central point. Use page to paginate large result sets.
codeoptionalstringZIP or postal code as the center point. Must be used with 'country'.
countryoptionalstringCountry of the base ZIP code in ISO 3166-1 alpha-2 format. Required when using 'code'.
latoptionalfloatLatitude of the central point (-90 to 90). Must be used together with 'long'.
longoptionalfloatLongitude of the central point (-180 to 180). Must be used together with 'lat'.
radiusrequiredfloatDistance from the central point. Max: 100 km / 100 mi. Must be greater than 0.
unitoptionalstringdefault: kmDistance unit. Supported: 'km', 'mi', 'yd', 'm', 'ft', 'in'. Default: km.
pageoptionalintegerdefault: 1Page number for paginated results (up to 500 per page).
Returns 200 OK with pagination metadata and a results array of ZIP code objects sorted by distance.
total_resultsTotal number of ZIP codes found within the radius.
total_pagesTotal pages available (up to 500 results per page).
current_pageCurrent page number.
current_page_sizeNumber of results in the current page.
resultsArray of ZIP code objects within the radius, sorted by distance.
Each element in the results array has the following fields:
codePostal/ZIP code of the location.
regionRegion, state, or province where the postal code is located.
region_codeISO or internal code representing the region.
cityCity associated with the ZIP code.
districtDistrict or neighborhood, if available.
distanceDistance from the central point in the requested unit.
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.
The specified radius is out of the acceptable range. Please check the documentation for valid radius limits.
Latitude must be between -90 and 90.
Only ISO 3166-1 alpha-2 codes country codes are supported.
The provided base postal/zip code does not exist in our database.