geocode
Convert an address or place name into WGS84 latitude/longitude coordinates. Returns a confidence score to indicate result reliability.
Instructions
Convert an address or place name into WGS84 coordinates (lat/lon).
Returns: formatted_address (string), coordinates {lat, lon}, city, country, confidence (0–1).
WHEN TO USE: When you have a human-readable address and need lat/lon. DO NOT USE: For coordinates-to-address (use reverse_geocode). For real-time user typing (use autocomplete).
CONFIDENCE: Score below 0.6 means the result is ambiguous — ask the user to clarify the address before proceeding. Score above 0.85 is reliable.
CACHING: Within an agent session, never re-geocode the same address string. Cache the result and reuse it.
COUNTRY BIAS: Always pass countries when the user's region is known — dramatically improves accuracy for short or ambiguous addresses (e.g. "Springfield" returns the right one).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Full address or place name to geocode. | |
| countries | No | ISO 3166-1 alpha-2 country codes to bias results. Comma-separated, max 4. Pass this whenever the user's country is known. | |
| limit | No | Max results to return. Default 5, max 25. Use 1 when you need a single best match. | |
| lang | No | Response language code (BCP 47). Default: en. | |
| focus.lat | No | Latitude to bias results toward (e.g. user's current location). Range: -90 to 90. | |
| focus.lon | No | Longitude to bias results toward. Range: -180 to 180. |