Boundaries

How it works

The first time anyone asks for a boundary we fetch it from OpenStreetMap, repair invalid rings, and store it in our database with its hierarchy, bounding box, area and population. Every later request, from anyone, is served from there. If two requests ask for the same new boundary at once, one fetches and the other waits a moment, so the upstream services see one request.

Search by name

Free, and works without a key (20 calls a minute per IP). Narrow it with country, kind, admin_level or near (a lat,lon to prefer). Results carry the parents, so you can tell Portland, Oregon from Portland, Maine before you pay for a polygon.

curl "https://geo-coder-service.vercel.app/v1/boundaries/search?q=Portland"

Get the polygon

get_boundary returns a GeoJSON Feature with the polygon and its properties. Choose detail (low, medium, high or full) and add include=parents or include=children for the hierarchy. It costs 1 unit; detail=low also works without a key.

curl "https://geo-coder-service.vercel.app/v1/boundaries/r396499?detail=medium&include=parents" \  -H "Authorization: Bearer $GEOCODE_API_KEY"

Everything at a point

reverse_boundaries returns every boundary containing a coordinate, country first down to the smallest district, plus postcode areas. One unit.

curl "https://geo-coder-service.vercel.app/v1/boundaries/reverse?lat=37.8044&lon=-122.2712" \  -H "Authorization: Bearer $GEOCODE_API_KEY"

Subdivisions

list_children lists a boundary's direct subdivisions: a country's states, a state's counties. Free and public. Without admin_level it picks the next level that exists.

curl "https://geo-coder-service.vercel.app/v1/boundaries/r165475/children"

Which points are inside

contains_points tests up to 10,000 [lon, lat] points against one boundary and returns a boolean per point. 1 unit per 1,000 points.

curl -X POST "https://geo-coder-service.vercel.app/v1/boundaries/r62422/contains" \  -H "Authorization: Bearer $GEOCODE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"points":[[13.405,52.52],[2.35,48.86]]}'

Merge boundaries

union_boundaries merges up to 50 boundaries into one polygon, minus any you exclude: three counties minus one city. 1 unit per boundary. For a zone written in words, use Areas.

curl -X POST "https://geo-coder-service.vercel.app/v1/boundaries/union" \  -H "Authorization: Bearer $GEOCODE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"include":["r396499","r396479"],"exclude":["r2833530"],"detail":"low"}'

Export a file

export_boundary builds GeoJSON, KML, WKT, SVG or GML once and redirects to a permanent URL on our CDN, which suits GIS tools and large polygons. See Detail & formats.

curl "https://geo-coder-service.vercel.app/v1/boundaries/r62422.kml?detail=medium" \  -H "Authorization: Bearer $GEOCODE_API_KEY"

Attribution

Boundaries are OpenStreetMap data under the ODbL. Every response includes an attribution string; show “© OpenStreetMap contributors” wherever you display a boundary from Geocode AI.