CTRL+K
ZIP Code Distance API is a quick solution to calculate straight-line distance (as-the-crow-flies), not the drive distance, between ZIP codes and postal codes. You can use this API in two ways:
You can also configure the distance measuring unit to return the calculated distance value per your need. Supported distance measuring units are `mi` (mile), `km` (kilometer), `m` (meter), `ft` (feet), `yd` (yard), `in` (inch). But, ZIP Code Distance API uses `km` (kilometer) as default distance measuring unit.
ZIP Code Distance API has vast usage in businesses like to:
You can use a ZIP code or a postal code at the base point, to calculate distance to your provided list of ZIP codes or postal code.
You can also select a set of location coordinates (latitude, longitude) as the base to calculate distance to the provided list of ZIPs.
ZIP Code Distance API can compare up to 100 ZIP codes or postal codes at a time in both modes. When pairing up 100 ZIP codes, it'll make up to 4950 pairs.
ZIP Code Distance API allows to convert distance between ZIP codes in a wide range of distance measuring units per your need. Allowed distance measuring units are `mi` (miles), `km` (kilometers), `m` (meters), `ft` (feets), `yd` (yards), `in` (inches). Though, `km` (kilometer) is the default unit.
$ pip install requests
To use ZIP Code Distance endpoint, you can include the following fields in the JSON body:
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
| compare | Yes | Array | - | List of ZIP or postal codes to calculate distance from the base point. All codes must exist in the same 'country'. |
| code | No | String | - | Base ZIP or postal code from which distances will be calculated. Must be provided together with 'country'. |
| country | No | String | - | Country where the ZIP/postal codes exist. Must be in ISO 3166-1 alpha-2 format. Must be provided together with 'code'. |
| lat | No | Number | - | Base latitude coordinate from which distances will be calculated. Must be provided together with 'long'. |
| long | No | Number | - | Base longitude coordinate from which distances will be calculated. Must be provided together with 'lat'. |
| unit | No | String | km | Distance measuring unit. Allowed values: 'km', 'mi', 'yd', 'm', 'ft', 'in'. |
You must provide either a pair of lat and long or a combination of code and country as the required fields to specify the origin location. If both lat/long and code/country are provided in the request, the code and country combination will take precedence.
$ pip install requests
To use ZIP Code Distance Match endpoint, you can include the following fields in the JSON body:
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
| codes | Yes | Array | - | List of ZIP or postal codes to find pairs within the specified distance. All codes must exist in the same country. |
| country | Yes | String | - | Country where the ZIP/postal codes exist. Must be in ISO 3166-1 alpha-2 format. |
| distance | No | Number | 100 | Upper threshold distance value. All pairs of ZIP codes within this distance will be returned. |
| unit | No | String | km | Distance measuring unit. Allowed values: 'km', 'mi', 'yd', 'm', 'ft', 'in'. |
For a comprehensive view of the API response structure and detailed field descriptions, explore the interactive Response Table. For ZIP Code distance API click here and for ZIP Code Distance Match API click here.
| HTTP Status | Reasons |
|---|---|
| 400 | (1) A maximum of 100 postal/zip codes can be processed per request.
(2) The provided unit symbol is invalid. Please refer to the documentation for supported units.
(3) Only ISO 3166-1 alpha-2 country codes are supported.
(4) Latitude must be between -90 and 90.
(5) Longitude must be between -180 and 180. |
| 404 | (1) None of the provided postal/zip codes were found in our database. |
You can use ZIP Codes Distance API to find distance to a list of ZIP codes or postal codes from any location point. All you need to provide is a list of ZIP codes or postal codes, a location coordinates and the country where they exist to calculate distance using ZIP Codes Distance API.
Pass all these parameters in the JSON body: lat (latitude), long (longitude), compare (array of ZIP/postal codes), and country (ISO 3166-1 alpha-2 code).
Let’s find the distance to E1 0AZ, HD1 1AB, OX1 1PU postcodes from location (lat: 51.5132336, long: -0.2273734) in the United Kingdom. Here is a curl request to do that:
# Response { "result_count": 3, "results": [ { "code": "E1 0AZ", "distance": 11.977 }, { "code": "HD1 1AB", "distance": 259.566 }, { "code": "OX1 1PU", "distance": 76.004 } ] }curl -s -X POST "https://api.apifreaks.com/v1.0/zipcode/distance?apiKey=API-KEY" \ -H "Content-Type: application/json" \ -d '{ "lat": 51.5132336, "long": -0.2273734, "compare": ["E1 0AZ", "HD1 1AB", "OX1 1PU"], "country": "GB" }'
All the distances in the above response are measured in kilometers (km), the default distance measuring unit. But, you can specify your choice of unit.
ZIP Codes Distance API can respond in JSON or XML formats for all requests. But, it responds in JSON format by default. Pass format=xml URL parameter along with your request to convert the API response in XML format. Here is a curl request to do that:
# Response <CodeDistance> <result_count>3</result_count> <results> <code_distance> <code>E1 0AZ</code> <distance>11.977</distance> </code_distance> <code_distance> <code>HD1 1AB</code> <distance>259.566</distance> </code_distance> <code_distance> <code>OX1 1PU</code> <distance>76.004</distance> </code_distance> </results> </CodeDistance>curl -s -X POST "https://api.apifreaks.com/v1.0/zipcode/distance?format=xml&apiKey=API-KEY" \ -H "Content-Type: application/json" \ -d '{ "lat": 51.5132336, "long": -0.2273734, "compare": ["E1 0AZ", "HD1 1AB", "OX1 1PU"], "country": "GB" }'
Given a list of ZIP codes, their country and an upper threshold on distance between them, you can find all pairs of ZIP codes in the list that are within the range of specified distance.
Suppose that you‘ve 5 US ZIP codes `71149`, `56517`, `54510`, `51549` and `10009`. Lets find out all ZIP codes pairs that are within 1000 miles from each other. Here is a curl request to do that:
# Response { "result_count": 2, "results": [{ "code_1": "56517", "code_2": "51549", "distance": 442.561 }, { "code_1": "71149", "code_2": "51549", "distance": 605.837 }] }curl -s -X POST "https://api.apifreaks.com/v1.0/zipcode/distance/match?apiKey=API-KEY" \ -H "Content-Type: application/json" \ -d '{ "codes": ["71149", "56517", "54510", "51549", "10009"], "country": "US", "distance": 1000, "unit": "mi" }'
The above response includes all the ZIP codes that up to 1000 miles apart.
To use the ZIP Code Distance and Distance Match APIs, API credits are required. Charges apply only for successful queries, defined by a 2xx status code. If a request results in a 4xx or 5xx status code, no credits will be deducted, and any credits already charged will be refunded.