Radius Search Endpoint

On this page, we'll dive into the radius search endpoint you can use to find all postal codes within a given radius.

Each call to this endpoint counts as 10 requests and returns one page of up to 10,000 postal codes. A wide radius in a dense country such as GB, CA or NL can hold more: see has_more and page.

GET/v1/radius

Find Codes Within Radius

This endpoint returns the postal codes within a specified radius of a given postal code, closest first. total is the number of postal codes in the radius; when has_more is true, request the next page.

Required attributes

Name
code
Type
string
Description
The postal code to search around. Example: 99501
Name
radius
Type
integer
Description
The radius to search within (max 500). Example: 50
Name
country
Type
string
Description
Two letter country code. Example: us

Optional attributes

Name
unit
Type
string
Description
Unit for distance calculation. Options: km, miles. Default: km. mi is accepted as an alias for miles.
Name
page
Type
integer
Description
The page of the results, from 1. Default: 1.
Name
limit
Type
integer
Description
Postal codes per page, at most 10000 (a larger limit reads as 10000, and one that is no whole number from 1 as the default). Default: 10000.

Request

GET

/v1/radius

curl -G "https://api.zipcodestack.com/v1/radius?code=99501&radius=50&country=us&unit=km" \
    -H "apikey: YOUR-API-KEY"

Full Response

{
    "query": {
        "code": "99501",
        "unit": "km",
        "radius": 50,
        "country": "us"
    },
    "results": [
        {
            "code": "99502",
            "city": "Anchorage",
            "state": "AK",
            "city_en": "Anchorage",
            "state_en": "Alaska",
            "distance": 5.23
        },
        {
            "code": "99503",
            "city": "Anchorage",
            "state": "AK",
            "city_en": "Anchorage",
            "state_en": "Alaska",
            "distance": 8.45
        }
    ],
    "total": 2,
    "page": 1,
    "limit": 10000,
    "has_more": false
}