Loading
Loading
Find all pairs of ZIP or postal codes from a provided list that fall within a specified distance threshold of each other. Returns every matched pair with their calculated distance.
Send a list of up to 100 ZIP codes and a maximum distance threshold. The API evaluates all combinations and returns pairs that are within the threshold. Useful for proximity-based filtering and delivery zone analysis.
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 containing a codes array of postal codes, an optional distance threshold, an optional country, and an optional unit for the distance unit.
{
"codes": [
"10001",
"11201",
"10301"
],
"country": "US",
"distance": 50,
"unit": "km"
}codesrequiredArrayList of ZIP or postal codes to find pairs within the specified distance. Max 100.
countryrequiredStringCountry of the ZIP/postal codes in ISO 3166-1 alpha-2 format.
distanceoptionalFloatdefault: 100Maximum distance threshold. All pairs within this distance are returned.
unitoptionalStringdefault: kmDistance measuring unit. Allowed: 'km', 'mi', 'yd', 'm', 'ft', 'in'. Default: km.
Returns 200 OK with result_count and a results array of matched pairs, each with two codes and their distance.
result_countTotal number of postal code pairs returned.
Array of matched postal code pairs with distance.
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.