> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# geocode

> Convert an address or place name to coordinates

Forward geocode: turn a text query (address, place name, or landmark) into geographic coordinates. Results are ranked by relevance and include a confidence score.

You can bias results towards a location with `focus_lat`+`focus_lon`, or restrict to specific countries with `country` (comma-separated ISO 3166-1 alpha-3 codes). Supply `focus_lat`+`focus_lon` whenever you have any spatial context — a visible viewport, a previous result, a known anchor. Common place names like "Cambridge", "Bath", or "Lebanon" exist in several countries; a focus point picks the one the user means.

## Example prompts

* "Where is Buckingham Palace?"
* "Find the coordinates for 10 Downing Street, London"
* "Geocode 'Empire State Building' and tell me the lat/lng"
* "What are the coordinates for Springfield? I mean the one in Illinois."

## What you get back

A list of matching locations, each with coordinates (lat/lng), a full label, country, region, district (borough or municipality, e.g. "City of Westminster"), locality, optional confidence score (omitted when 1.0; present when below), and the result type (venue, address, street, locality, etc.).

When all results share the same country / country\_code / region, those fields are hoisted to a top-level `context` object so they aren't repeated on every result. Read shared admin from `context`, per-result variation from `results[i]`.

## Tips for landmark queries

* **Qualify with city context.** `"Big Ben, London"` resolves much more reliably than `"Big Ben"` alone — the comma form lets the parser treat the city as administrative context.
* **Plain street addresses don't need extra context** — `"10 Downing Street, London"` is enough.

If you're driving the tool from an LLM, mentioning these hints in the system prompt often improves results without any code changes.

## Map rendering

Responses include a `render` envelope with a `point` layer for the matched candidates (per-feature `properties` carries name, label, place\_type, confidence). Pass `compact: true` for summary-only responses. See [response defaults & controls](/mcp/defaults) and [render envelopes](/mcp/render-envelopes).

## Example response

```json theme={null}
{
  "structuredContent": {
    "results": [
      {
        "name": "Buckingham Palace",
        "label": "Buckingham Palace, London, England, United Kingdom",
        "coordinates": { "lat": 51.501, "lng": -0.142 },
        "place_type": "venue"
      }
    ],
    "context": { "country": "United Kingdom", "country_code": "GBR" },
    "render": [
      { "kind": "point", "label": "Geocoded matches", "data": {/* FeatureCollection */}, "bbox": [/* … */] }
    ]
  }
}
```