geocode
Convert place names to geographic coordinates and address details using OpenStreetMap data. Retries with simpler queries if initial search fails.
Instructions
Forward geocode a place name to coordinates.
Searches the OpenStreetMap/Nominatim database for places matching
the query and returns coordinates, bounding boxes, and address details.
Args:
query: Place name or address to search for (e.g. "Boulder, Colorado")
limit: Maximum results (1-50, default 5)
countrycodes: Comma-separated ISO 3166-1 country codes to filter (e.g. "us,gb")
language: Preferred response language (e.g. "en", "de", "fr")
output_mode: "json" (default) or "text"
Returns:
List of matching places with coordinates, bbox, and address details
CRITICAL — LLM retry workflow when no results are found:
Nominatim works best with simple, well-known place names. Specific
or compound names (e.g. "Strood Causeway, Mersea Island, UK") often
return nothing.
If the query returns no results, you MUST retry automatically — do
NOT ask the user. Follow this cascade:
1. Remove qualifiers and landmarks — keep only the core place name.
"Strood Causeway, Mersea Island, UK" → "Mersea Island, UK"
"Portland Harbor, Maine" → "Portland, Maine"
2. Simplify further — drop region/country qualifiers.
"Mersea Island, UK" → "Mersea Island"
"Portland, Maine" → "Portland"
3. Use countrycodes to narrow broad queries (e.g. countrycodes="gb").
4. If the place is near a well-known location, geocode that instead
and report the approximate area.
5. Try alternative or official names — "The Strood" instead of
"Strood Causeway", etc.
Always retry at least twice with progressively simpler terms before
telling the user the location could not be found.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No | ||
| countrycodes | No | ||
| language | No | ||
| output_mode | No | json |