Skip to content

Territories

Sales regions, delivery zones and dealer areas are usually made of counties, cities or postcodes. Build them from real boundaries instead of drawing them by hand.

A territory is a list of boundary ids

Store each territory as the ids of the boundaries it is made of, not as a polygon you drew. Ids are stable OpenStreetMap relations, so the territory follows the real border and you can always rebuild the shape. Search is free and needs no key.

curl "https://geocodeai.dev/v1/boundaries/search?q=Alameda%20County"

Pass country and kind to narrow it (country=US&kind=county). For a territory defined by a whole region, list its children and keep the ids you need.

Assign locations

Test customer or order locations against each boundary of a territory, up to 10,000 points per call, one unit per 1,000 points. A location inside any of the territory's boundaries belongs to it.

curl -X POST "https://geocodeai.dev/v1/boundaries/r396499/contains" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"points":[[-122.2712,37.8044],[-121.8863,37.3382]]}'

For one location at a time, reverse lookup returns every boundary that contains it, from the country down, so you can match its county or city id against your territories directly.

Draw the territory

A map needs one shape. Merge the territory's boundaries into a single GeoJSON polygon, simplified for maps, and cache it: county and city lines change rarely.

curl -X POST "https://geocodeai.dev/v1/boundaries/union" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include":["r396499","r396462"],"exclude":[],"detail":"low"}'

If the territory is written in a contract (“Alameda and Contra Costa counties, excluding the City of Oakland”), send the wording to Areas and get one validated polygon back instead.

Recipe: dealer territories with vehicle images

Dealer groups route each buyer to the dealer whose territory they live in, then show that dealer's stock. Car Image, also made by Meter, has a guide that combines these territory calls with its vehicle images: dealer territories and inventory maps.