<!-- Generated by `just docs` from catalog/toolkits/google_maps.yaml, catalog/expansions/google_maps.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Google Maps Platform

Maps and places. Turn an address into coordinates, get directions and travel times, and look up businesses, elevation, and time zones.

| Property | Value |
| --- | --- |
| Slug | `google_maps` |
| Definition version | `0.1.0` |
| Base URL | `https://maps.googleapis.com/maps/api` |
| Auth schemes | `api_key` |
| Action tools | 13 |
| By class | 13 read |
| Triggers | 0 |
| Provider rate limit | not declared, so outbound calls are unpaced |

## Measured routing accuracy

26 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 13 cases written by hand and 13 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 17/26 | 65.4% |
| top-8 | 21/26 | 80.8% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `api_key`

| Property | Value |
| --- | --- |
| Placement | `query` |
| Name | `key` |
| Rendered as | `{key}` |

Submit the key with `ConnectionsService` rather than putting it in a request; it is sealed at rest and never returned.

## Tools

13 action tools. The catalog-wide slug is `google_maps.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `google_maps.geocode_address`

Look up the latitude/longitude, formatted address, and place id for a street address or place name using Google Maps geocoding. Use when the user gives an address or place name in words and wants coordinates or a place id back. For the reverse direction, turning coordinates into an address, use reverse_geocode instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /geocode/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string | **yes** | Street address or place name to geocode, e.g. "1600 Amphitheatre Parkway, Mountain View, CA". |
| `language` | string | no | Language for the returned formatted address, e.g. "es". |
| `region` | string | no | ccTLD bias for ambiguous results, e.g. "uk" to prefer United Kingdom matches. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `results` | array of object |  |
| `results[].formatted_address` | string |  |
| `results[].geometry` | object |  |
| `results[].geometry.location` | object |  |
| `results[].geometry.location_type` | string |  |
| `results[].place_id` | string |  |
| `results[].types` | array of string |  |
| `status` | string |  |

Also retrieved by: "turn this street address into coordinates", "what's the lat and long for our new office", "pin this place name down to a spot on the map", "I have an address, I need the geocode for it".

### `google_maps.reverse_geocode`

Look up the street address (or the nearest addresses and place types) at a given latitude/longitude using Google Maps reverse geocoding. Use when the user has coordinates, from a GPS fix or a map click, and wants to know what's there or get a mailing address. For turning an address into coordinates, use geocode_address instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /geocode/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `language` | string | no | Language for the returned formatted address, e.g. "es". |
| `latlng` | string | **yes** | Comma-separated "latitude,longitude" to reverse-geocode, e.g. "40.714224,-73.961452". |
| `result_type` | string | no | Comma-separated place types to restrict results to, e.g. "street_address" or "postal_code". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `results` | array of object |  |
| `results[].formatted_address` | string |  |
| `results[].place_id` | string |  |
| `results[].types` | array of string |  |
| `status` | string |  |

Also retrieved by: "what's actually at these coordinates", "figure out the street address from this gps fix", "somebody dropped a pin, tell me what's there", "translate this lat/long back into a mailing address".

### `google_maps.get_directions`

Get turn-by-turn Google Maps driving, walking, bicycling, or transit directions between an origin and a destination, with distance and duration per leg and per step. Use when the user wants a route or needs to know how to get from one place to another. For travel time or distance across many origins and destinations at once rather than one route, use get_distance_matrix.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /directions/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `alternatives` | boolean | no | Return multiple alternative routes instead of just the best one. |
| `avoid` | string | no | Comma-separated features to route around: "tolls", "highways", "ferries", "indoor". |
| `departure_time` | string | no | Unix timestamp, or "now", for transit/driving-time-in-traffic routes. |
| `destination` | string | **yes** | Ending point as an address, "lat,lng", or "place_id:ID". |
| `mode` | string, one of driving, walking, bicycling, transit | no | Travel mode. Default driving. |
| `origin` | string | **yes** | Starting point as an address, "lat,lng", or "place_id:ID". |
| `waypoints` | string | no | Pipe-separated intermediate stops, each an address, "lat,lng", or "place_id:ID". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `routes` | array of object |  |
| `routes[].legs` | array of object |  |
| `routes[].legs[].distance` | object |  |
| `routes[].legs[].duration` | object |  |
| `routes[].legs[].end_address` | string |  |
| `routes[].legs[].start_address` | string |  |
| `routes[].legs[].steps` | array of object |  |
| `routes[].summary` | string |  |
| `routes[].warnings` | array of string |  |
| `status` | string |  |

Also retrieved by: "how do I drive from the airport to the hotel", "map out a walking route between these two spots", "I need turn by turn directions for this trip", "what's the fastest way to get across town from here".

### `google_maps.get_distance_matrix`

Get travel distance and duration for every combination of several origins and destinations at once via the Google Maps Distance Matrix API. Use when the user wants to compare travel time or distance across multiple places, e.g. "which of these three offices is closest to each candidate's address", rather than one turn-by-turn route. For a single route's step-by-step directions, use get_directions.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /distancematrix/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `departure_time` | string | no | Unix timestamp, or "now", to factor in current traffic for driving. |
| `destinations` | string | **yes** | Pipe-separated ending points, each an address or "lat,lng". |
| `mode` | string, one of driving, walking, bicycling, transit | no | Travel mode. Default driving. |
| `origins` | string | **yes** | Pipe-separated starting points, each an address or "lat,lng". |
| `units` | string, one of metric, imperial | no | Unit system for the returned distance text. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `destination_addresses` | array of string |  |
| `origin_addresses` | array of string |  |
| `rows` | array of object |  |
| `rows[].elements` | array of object |  |
| `rows[].elements[].distance` | object |  |
| `rows[].elements[].duration` | object |  |
| `rows[].elements[].status` | string |  |
| `status` | string |  |

Also retrieved by: "which warehouse is closest to each of these delivery addresses", "compare drive times from our three offices to the client", "build a grid of travel time between every pair of these locations", "rank these candidate addresses by how far they are from headquarters".

### `google_maps.get_elevation`

Get the ground elevation in meters at one or more specific latitude/longitude points via the Google Maps Elevation API. Use when the user names exact points and asks how high up a location is. For elevation sampled evenly along a route rather than named points, use get_elevation_along_path instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /elevation/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `locations` | string | **yes** | Pipe-separated "lat,lng" points to sample, e.g. "39.7391536,-104.9847034\|36.455556,-116.866667". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `results` | array of object |  |
| `results[].elevation` | number |  |
| `results[].location` | object |  |
| `results[].location.lat` | number |  |
| `results[].location.lng` | number |  |
| `results[].resolution` | number |  |
| `status` | string |  |

Also retrieved by: "how high above sea level is this spot", "check the altitude at these coordinates", "I want the ground height at a couple of points".

### `google_maps.get_elevation_along_path`

Get a Google Maps elevation profile: ground elevation in meters at a set number of evenly spaced points sampled along a path of latitude/longitude waypoints. Use when the user wants elevation change over the length of a route or hike rather than at a few named points; for exact named points, use get_elevation instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /elevation/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Pipe-separated "lat,lng" waypoints defining the path to sample along. |
| `samples` | integer | **yes** | Number of equally spaced points to sample along the path, minimum 2. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `results` | array of object |  |
| `results[].elevation` | number |  |
| `results[].location` | object |  |
| `results[].location.lat` | number |  |
| `results[].location.lng` | number |  |
| `results[].resolution` | number |  |
| `status` | string |  |

Also retrieved by: "chart the elevation gain over this hiking route", "sample the terrain height along this trail", "I need an elevation profile for the whole path, not just the ends".

### `google_maps.get_timezone`

Get the time zone id, name, and UTC offset (including any daylight saving adjustment) for a location at a given moment via the Google Maps Time Zone API. Use when the user asks what time zone a place is in or what the local time offset is there. The moment matters because the offset changes with daylight saving.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /timezone/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `language` | string | no | Language for the returned time zone name, e.g. "es". |
| `location` | string | **yes** | Comma-separated "latitude,longitude" to look up, e.g. "40.714224,-73.961452". |
| `timestamp` | integer | **yes** | Unix timestamp (seconds) of the moment to compute the offset at, since it varies by date under daylight saving. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `dstOffset` | integer |  |
| `rawOffset` | integer |  |
| `status` | string |  |
| `timeZoneId` | string |  |
| `timeZoneName` | string |  |

Also retrieved by: "what timezone does this coordinate fall in", "is daylight saving in effect out there right now", "tell me the utc offset for this spot on a given date".

### `google_maps.search_places_by_text`

Search Google Maps places by a free-text query like a business name, category, or address, e.g. "pizza in Chicago" or "24-hour pharmacies near me". Use when the user describes what they're looking for in words. For places near a known point without a text description, use search_nearby_places; for matching one specific known name to a single result, use find_place.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/textsearch/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `location` | string | no | Optional "lat,lng" bias point to search around. |
| `opennow` | boolean | no | Only return places open at the time of the call. |
| `query` | string | **yes** | Free-text search, e.g. "vegan restaurants in Austin, TX". |
| `radius` | integer | no | Bias radius in meters around location, max 50000. |
| `type` | string | no | Restrict to one place type, e.g. "restaurant" or "pharmacy". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `next_page_token` | string |  |
| `results` | array of object |  |
| `results[].business_status` | string |  |
| `results[].formatted_address` | string |  |
| `results[].geometry` | object |  |
| `results[].geometry.location` | object |  |
| `results[].name` | string |  |
| `results[].place_id` | string |  |
| `results[].rating` | number |  |
| `results[].types` | array of string |  |
| `results[].user_ratings_total` | integer |  |
| `status` | string |  |

Also retrieved by: "find late night ramen spots downtown", "look up ATMs near the convention center by description", "I'm hunting for a bookstore that matches this vibe", "search for vegan brunch places in this neighborhood".

### `google_maps.search_nearby_places`

Find Google Maps places of a given type or keyword near a specific latitude/longitude, e.g. coffee shops within 500 meters of a point. Use when the user wants results ranked by proximity to a location rather than by a free-text description. For a text query without a fixed center point, use search_places_by_text instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/nearbysearch/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `keyword` | string | no | Free-text term to match against place name, type, or reviews. |
| `location` | string | **yes** | Center point as "lat,lng" to search around. |
| `opennow` | boolean | no | Only return places open at the time of the call. |
| `radius` | integer | no | Search radius in meters, max 50000. Omit when rankby is "distance". |
| `rankby` | string, one of prominence, distance | no | How to order results. "distance" requires keyword or type and ignores radius. |
| `type` | string | no | Restrict to one place type, e.g. "cafe" or "gas_station". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `next_page_token` | string |  |
| `results` | array of object |  |
| `results[].business_status` | string |  |
| `results[].geometry` | object |  |
| `results[].geometry.location` | object |  |
| `results[].name` | string |  |
| `results[].place_id` | string |  |
| `results[].rating` | number |  |
| `results[].types` | array of string |  |
| `results[].user_ratings_total` | integer |  |
| `results[].vicinity` | string |  |
| `status` | string |  |

Also retrieved by: "what's within walking distance of this pin", "show me gas stations close to this exact point", "list the coffee shops inside a five minute radius here".

### `google_maps.find_place`

Match a specific known business name, address, or place description to a single best Google Maps place, returning its place id and a short summary. Use when the user already knows what they're looking for by name and wants the one right match rather than a list of candidates to pick from. For browsing multiple results for a looser query, use search_places_by_text instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/findplacefromtext/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `fields` | string | no | Comma-separated fields to return, e.g. "place_id,name,formatted_address,geometry". |
| `input` | string | **yes** | The name, address, or description of the place to match, e.g. "Museum of Modern Art New York". |
| `locationbias` | string | no | Bias toward an area, e.g. "circle:2000@47.6918452,-122.2226413". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `candidates` | array of object |  |
| `candidates[].formatted_address` | string |  |
| `candidates[].geometry` | object |  |
| `candidates[].geometry.location` | object |  |
| `candidates[].name` | string |  |
| `candidates[].place_id` | string |  |
| `status` | string |  |

Also retrieved by: "track down the exact listing for this one restaurant by name", "I know exactly which business I mean, get me its record", "match this business name to its one real place entry".

### `google_maps.get_place_details`

Get full Google Maps details for one place by its place id: phone number, website, opening hours, rating, and recent reviews. Use after find_place, search_places_by_text, or search_nearby_places once the user wants more than the short summary those return, e.g. "is it open right now" or "what's their phone number".

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/details/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `fields` | string | no | Comma-separated fields to return, e.g. "name,formatted_phone_number,opening_hours". Omit for the full default set. |
| `language` | string | no | Language for the returned text fields, e.g. "es". |
| `place_id` | string | **yes** | Place id to look up, from find_place, search_places_by_text, or search_nearby_places. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `result` | object |  |
| `result.business_status` | string |  |
| `result.formatted_address` | string |  |
| `result.formatted_phone_number` | string |  |
| `result.geometry` | object |  |
| `result.geometry.location` | object |  |
| `result.international_phone_number` | string |  |
| `result.name` | string |  |
| `result.opening_hours` | object |  |
| `result.opening_hours.open_now` | boolean |  |
| `result.opening_hours.weekday_text` | array of string |  |
| `result.place_id` | string |  |
| `result.rating` | number |  |
| `result.reviews` | array of object |  |
| `result.reviews[].author_name` | string |  |
| `result.reviews[].rating` | integer |  |
| `result.reviews[].relative_time_description` | string |  |
| `result.reviews[].text` | string |  |
| `result.url` | string |  |
| `result.user_ratings_total` | integer |  |
| `result.website` | string |  |
| `status` | string |  |

Also retrieved by: "is this place open right now", "grab their phone number and hours off the listing", "pull up recent reviews for this spot", "what's the website on file for that business".

### `google_maps.autocomplete_place`

Get Google Maps place predictions as a user types a partial address or business name, for building a search-as-you-type autocomplete field. Use when the input is an incomplete, in-progress query rather than a finished search someone already typed out fully. For predicting the rest of a general search phrase instead of an actual place, use autocomplete_query.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/autocomplete/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `components` | string | no | Restrict to a country, e.g. "country:us". |
| `input` | string | **yes** | The partial text typed so far, e.g. "123 Main St, Sp". |
| `location` | string | no | Optional "lat,lng" bias point for predictions. |
| `radius` | integer | no | Bias radius in meters around location. |
| `types` | string | no | Restrict predictions to a category, e.g. "address", "establishment", or "geocode". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `predictions` | array of object |  |
| `predictions[].description` | string |  |
| `predictions[].place_id` | string |  |
| `predictions[].structured_formatting` | object |  |
| `predictions[].structured_formatting.main_text` | string |  |
| `predictions[].structured_formatting.secondary_text` | string |  |
| `status` | string |  |

Also retrieved by: "suggest addresses as someone types into this field", "build a type-ahead box for picking a location", "offer place suggestions while the input is still partial".

### `google_maps.autocomplete_query`

Predict likely search queries, not specific places, for a partial Google Maps text search, e.g. finishing "pizza near" as the user types. Use when the input is a general search phrase still being typed rather than a specific address or business name; for predicting an actual place to select, use autocomplete_place instead.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /place/queryautocomplete/json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | string | **yes** | The partial search phrase typed so far, e.g. "pizza near". |
| `location` | string | no | Optional "lat,lng" bias point for predictions. |
| `radius` | integer | no | Bias radius in meters around location. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `predictions` | array of object |  |
| `predictions[].description` | string |  |
| `predictions[].place_id` | string |  |
| `predictions[].structured_formatting` | object |  |
| `predictions[].structured_formatting.main_text` | string |  |
| `predictions[].structured_formatting.secondary_text` | string |  |
| `status` | string |  |

Also retrieved by: "guess what search phrase they're going for as they type", "suggest how to finish this half typed search term", "predict the rest of a vague search string, not a place".