Distance and radius search
ZIP code distance and radius API
Two endpoints for location logic built on postal codes: /v1/distance measures the distance from one code to up to 100 others, and /v1/radius returns every code within a radius around a code, with city, state and distance.
Example request and response
The /v1/distance endpoint, with the example from the documentation. Codes from compare that are not found are left out of results, so check for missing keys.
curl -G "https://api.zipcodestack.com/v1/distance?code=99501&compare=90210,15106&country=us&unit=km" \
-H "apikey: YOUR-API-KEY"
{
"query": {
"code": "99501",
"compare": ["90210", "15106"],
"country": "us",
"unit": "km"
},
"results": {
"90210": 3754.89,
"15106": 5115.42
}
}
Parameters and limits
| Field | What it contains |
|---|---|
| distance: code, compare | One source code and a comma-separated list of up to 100 codes to compare with. |
| radius: code, radius | The centre code and a radius of up to 500, in the chosen unit. Each result has code, city, state and distance. |
| country | Two-letter country code, for example us. |
| unit | km (default) or miles; mi works too. |
| Credits | Distance: 1 credit per calculated distance. Radius: 10 credits per request. |
Use cases
Delivery zones and shipping rates
Find every ZIP code within 25 miles of a warehouse, or price shipping by the distance between two codes.
Store and dealer locators
Sort locations by distance from the visitor's ZIP code without geocoding full addresses.
Lead routing and service areas
Assign a lead to the nearest branch, or check whether a customer is inside your service radius.
Radius search example
curl -G "https://api.zipcodestack.com/v1/radius?code=99501&radius=50&country=us&unit=km" \
-H "apikey: YOUR-API-KEY"
The response lists each postal code inside the radius with its city, state and distance from the centre code. The full reference is in the radius endpoint documentation.
Start on the free plan
The free plan includes 300 credits a month with 10 requests a minute, enough to try both endpoints. Paid plans start at $34.99 a month for 70,000 credits.
Frequently asked questions
How is the distance calculated?
What is the largest radius?
unit.