Polygon Search Endpoint

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

Each call to this endpoint counts as 10 requests and returns one page of up to 10,000 postal codes. A large polygon can hold more: see has_more and page.

POST/v1/polygon

Find Codes Inside Polygon

This endpoint returns the postal codes within a specified polygon area defined by coordinate pairs, closest to the polygon's centroid first. total is the number of postal codes in the polygon; when has_more is true, request the next page.

Required attributes

Name
country
Type
string
Description
Two letter country code (query parameter). Example: us
Name
coordinates
Type
array
Description
Array of coordinate pairs [longitude, latitude] defining the polygon. At least 2 and at most 1,000 coordinate pairs, in a body of at most 128 KiB; the ring is closed for you if the last pair differs from the first.

Optional attributes

Name
page
Type
integer
Description
The page of the results, from 1 (query parameter). 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 (query parameter). Default: 10000.

Limits

A polygon with more than 1,000 coordinate pairs or a body larger than 128 KiB is refused with a 422 before any search ("The polygon is too large: at most 1000 coordinate pairs."). So is a polygon whose search takes longer than 5 seconds because it covers too many postal codes ("The polygon covers too many postal codes to search in time. Split it into smaller polygons or use fewer coordinate pairs."). Split such a polygon into smaller ones. None of these answers is billed.

Request

POST

/v1/polygon

curl -X POST "https://api.zipcodestack.com/v1/polygon?country=us" \
    -H "apikey: YOUR-API-KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "coordinates": [
            [-149.9, 61.2],
            [-149.8, 61.2],
            [-149.8, 61.3],
            [-149.9, 61.3],
            [-149.9, 61.2]
        ]
    }'

Full Response

{
    "query": {
        "country": "us"
    },
    "results": [
        {
            "code": "99501",
            "city": "Anchorage",
            "state": "AK",
            "city_en": "Anchorage",
            "state_en": "Alaska",
            "latitude": 61.2181,
            "longitude": -149.9003,
            "distance": 0
        }
    ],
    "total": 1,
    "page": 1,
    "limit": 10000,
    "has_more": false
}