Loading
Loading
Calculate distances from a base point to a list of ZIP or postal codes. The base point can be a ZIP code + country or raw latitude/longitude coordinates. Supports up to 100 comparison codes per request.
Six distance units are supported: km (default), mi, yd, m, ft, and in. Each result includes the postal code and its calculated distance from the base point.
Authorize every request with your API key, passed either as a header or as a query parameter:
X-apiKeyapiKeyThis is version v1.0 of the API.
Optional query parameter to control the response format.
formatoptionalStringdefault: jsonResponse format: 'json' (default) or 'xml'.
The request body must be a JSON object with a base location (via code + country or lat/long) and a required compare array of postal codes.
{
"compare": [
"90210",
"10001"
],
"code": "33101",
"country": "US",
"unit": "km"
}comparerequiredArrayList of ZIP or postal codes to calculate distance from the base point. All codes must exist in the same 'country'. Max 100.
codeoptionalStringBase ZIP or postal code from which distances are calculated. Must be provided together with 'country'.
countryoptionalStringCountry of the ZIP/postal codes in ISO 3166-1 alpha-2 format. Required when using 'code' as base.
latoptionalFloatBase latitude coordinate (-90 to 90). Must be provided together with 'long'.
longoptionalFloatBase longitude coordinate (-180 to 180). Must be provided together with 'lat'.
unitoptionalStringdefault: kmDistance measuring unit. Allowed: 'km', 'mi', 'yd', 'm', 'ft', 'in'. Default: km.
Returns 200 OK with result_count and a results array containing each compared code and its distance.
result_countNumber of ZIP code distance results returned.
Array of ZIP code distance result objects.
Besides the response body, every response carries custom headers you can use to track credit usage, and concurrency usage on endpoints that enforce a concurrency limit. See the Custom Response Headers documentation and the endpoints with concurrency limits for more details.
X-Concurrent-Threadsheaderconcurrency-limited endpointsSpecifies the maximum number of concurrent requests allowed.
X-Concurrent-Threads-Activeheaderconcurrency-limited endpointsIndicates the number of active concurrent requests being processed.
X-AF-Credits-Costheaderall responsesSpecifies the number of credits consumed by the current request.
See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.
The provided unit symbol is invalid. Please refer to the documentation for supported units.
Only ISO 3166-1 alpha-2 codes country codes are supported.
A maximum of 100 postal/zip codes can be processed per request.
None of the provided postal/zip codes were found in our database.