Geocode a place name
geocodeRead-onlyIdempotent
Turn a free-text place name into ranked candidate locations with coordinates, type, and admin context. Matches exact, prefix, substring, fuzzy, exonym, and postcode queries from Overture open data.
Instructions
Free-text place name -> ranked candidate locations, from Overture divisions and places.
No Nominatim, no third-party geocoding API. Matches localities,
neighborhoods, regions, and countries by name (exact > prefix >
substring), falling back to named places if that doesn't fill `limit`.
Returns {"results": [{name, type, lat, lon, id (GERS), admin_context,
rank_score}, ...]}, budgeted like every other tool. Returns a structured
{"error": ...} instead of raising if the remote scan fails.
A query with no location context in it at all (a bare place name that
matches no division, e.g. "Blue Bottle Roastery") can't be bounded to a
region, so the places half of the search is skipped rather than
scanning the global places dataset — minutes, not seconds (#105). That
case comes back empty with a "note" saying so and what to do instead.
A misspelled name that matches no division literally ("Berekley", or
"Berekley, CA" — the region suffix is set aside first) gets one
close-spelling retry over the local divisions table (#215); those
results rank below any literal match, carry "matched_by": "fuzzy", and
come with a "note" naming the spelling they were corrected to.
A query that is entirely a postcode ("94110", "1011AB") is answered as
one (#223): one result per country whose address points carry that code,
with "type": "postcode", "country", "address_count" and a null "id" (a
postcode is not a GERS entity). Codes are shared across countries far
more often than not, so the alternates below the top row are real
ambiguity. The accompanying "note" carries the granularity caveat (a
Dutch code is a street block, a US ZIP a district) and the coverage
limits -- including the countries the addresses theme covers but that
carry no postcode values at all, which is why a valid postcode can still
come back empty.
Exonyms work too (#214): names are matched against Overture's ~100
localized alternates as well as its canonical one, so "Munich" answers
München and "Tokyo" answers 東京都. `name` is always the canonical
spelling; such rows carry an extra "matched_name" naming the alternate
that matched.
lang (#410) requests Overture's language-tagged name variant instead
of a division row's primary name, when the data has one for that row
and language: `name` becomes the variant and `name_primary` is added
only when it differs. Default: the stored `preferences()` lang, else
the primary name unchanged. Never invented or transliterated — only a
variant actually present in Overture's data is ever returned.
`PLACEROOT_HOME=<city/area>` (#406) sets a home region once at startup;
a bounded score bonus then nudges same-tier ambiguous namesakes (the
"which Springfield" case) toward it — a bias, never a filter, so a
distant result stays in the answer, just not first. Only when the bias
actually changed the top result does a "note" say so, e.g. "ranked
toward your configured home region (Seattle); pass a city/near hint to
override". No home configured -> no bias, no note, behavior unchanged.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Result-language code (2-3 lowercase letters, e.g. "de"). Overture-tagged name variants only — never transliterated or invented. Default: stored preference, else the primary name. | |
| limit | No | ||
| query | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||