Skip to main content
Glama

Resolve place to GERS id

resolve_place
Read-onlyIdempotent

Free-text place reference -> ranked, typed GERS ids to hold onto.

Instructions

Free-text place reference -> ranked, typed GERS ids to hold onto.

Turns something like "the Whole Foods on Lamar" or "Travis County" into
stable Overture ids: merges geocode()'s division matches (locality,
region, county, country, ...) with a name-filtered find_places search
(a business or POI), bbox-limited to near_lat/near_lon if given, else to
the ~20km vicinity of the top division match.

**Split the location out of the query, and pass `city`.** You know
things this server does not: that "san jose airport" means San Jose,
California, that the Eiffel Tower is in Paris, that a user asking about
"BASIS Silicon Valley" means Sunnyvale. This server knows only what
exists at which coordinates in the current Overture release. When the
location arrives inside one string, it has to guess which words are the
place — and it guesses from map data alone, where "san" names a division
in Henan and "palo" names one in Leyte. Given `city="San Jose, CA"` and
`query="airport"` there is nothing to guess.

A wrong hint costs a miss and a retry, never a wrong answer: `city`
only bounds where the search looks, and the returned rows still come
from the data. Pass `near_lat`/`near_lon` instead when you have real
coordinates — they are the strongest hint of all.

When nothing resolves for want of a location, the reply carries
`need: "location"` and a `retry_with` sketch rather than only prose,
so the second call can be made without parsing English.

Returns {"results": [{"id" (GERS), "kind": "division" | "place",
"name", "lat", "lon", "match": "exact" | "prefix" | "contains" |
"substring" | "fuzzy", plus "admin_context" for a division or
"category" for a place}, ...]}, ranked by match tier then prominence
("contains", places only, #475: the name holds the whole query or the
query the whole name, above "substring", which for a place can mean
one shared word; "fuzzy" — reached by close spelling rather than by
containing the query at all, #215 for divisions and #373 for places —
ranking below every literal match).
A place found through #373's alt-spelling/typo fallback additionally
carries "matched_by": "alt_name" | "fuzzy", and a top-level "note"
names the spelling actually matched. Budgeted like every other tool.
An unresolvable query returns {"results": []} — not an error. Returns a
structured {"error": ...} instead of raising if the remote scan fails
or the places dataset is missing columns this tool depends on.

lang (#410) requests Overture's language-tagged name variant, same as
geocode() — but only for "kind": "division" rows; "kind": "place" rows
(from find_places, out of scope for #410 this round) always carry
their primary name. Default: the stored `preferences()` lang, else the
primary name unchanged.
Division candidates come from geocode() (#406), so a configured
`PLACEROOT_HOME` nudges the same ambiguous-namesake ties this tool
merges from — see geocode()'s docstring. resolve_place does not add its
own disclosure note for that; its own ranking already leads with
distance to `near_lat`/`near_lon`/`city` when one is given.

country (#457, ISO 3166-1 alpha-2, also accepting alpha-3 and aliases
like "UK"/"USA", case-insensitive) composes with `city`: it constrains
the divisions half of the merge the same way it constrains geocode()
itself — `resolve_place("Cambridge", country="GB")` resolves the UK
Cambridge rather than whichever namesake ranks first unconstrained. An
unrecognized `country`, or one that disagrees with a country/region
suffix parsed off `query` itself, returns a structured
{"error": "bad_request", ...} naming both.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cityNo
langNoResult-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.
limitNo
queryYes
countryNo
near_latNo
near_lonNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.11.0
    • addedInput schema / properties / country
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Country"
      +}
  2. First observedv0.10.0

TDQS

Score is being calculated.