Areas

When to use it

Use Areas when the area isn't one named place: “Alameda and Contra Costa counties excluding Oakland”, a franchise territory, a fare zone from a city decree. For a single place, search and get is instant and costs one unit.

Request

Send text. Optionally add country (ISO code), source (who wrote it: an agency, a company) and seed, a point that must be inside the area. A run takes 30 seconds to a few minutes; keep the connection open, or call it from a background job.

curl -X POST "https://geo-coder-service.vercel.app/v1/areas" \  -H "Authorization: Bearer $GEOCODE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"text":"Alameda and Contra Costa counties, excluding the City of Oakland","country":"US"}'

How it works

1. Read. The agent works out which places to include and exclude: counties, cities, districts, airports, former municipalities.
2. Map. Each place is matched to a real boundary, clipped to land, and checked for the right kind and a plausible size.
3. Validate. Sizes, your seed point and overlaps are checked. Only a polygon that holds up comes back.

Response

HTTP 200 with areas: one entry per area the text defines (a fare table can define several), each with its geometry (GeoJSON), area_km2, and the parts it was built from, with role (include/exclude), name and confidence.

Rejections

If any place can't be mapped or the result fails validation, there is no polygon. You get 422 could_not_map with a reason per place: not_found or ambiguous. Fix the wording (add the country or the kind of place) and send it again.

{  "type": "…/docs/errors#could_not_map",  "title": "could_not_map",  "status": 422,  "code": "could_not_map",  "detail": {    "areas": [      {        "label": "general",        "reasons": [          {            "code": "not_found",            "message": "Couldn't find “former 南茅部町 (merged into 函館市 on 2004-12-01; areas such as 尾札部町, 臼尻町, 川汲町, 安浦町, 木直町, 古部町, 大船町, 豊崎町) should be excluded” on the map."          }        ]      }    ]  }}

Try it

Run the hard cases from the home page, or your own wording, on the trial page.