# Google Maps

Integrate Google Maps to access location data, geocoding, directions, and mapping services in your application.

- **Category:** developer tools
- **Auth:** OAUTH2, API_KEY
- **Tools:** 21
- **Triggers:** 0
- **Slug:** `GOOGLE_MAPS`
- **Version:** 20260211_00

## Frequently Asked Questions

### How do I set up custom Google OAuth credentials for Google Maps?

For a step-by-step guide on creating and configuring your own Google OAuth credentials with Devcaster, see [How to create OAuth2 credentials for Google Apps](https://devcaster.dev/auth/googleapps).

### Why am I seeing "App is blocked" when connecting Google Maps?

The OAuth client is requesting scopes that Google hasn't verified for that client. This usually happens when you add extra scopes beyond the defaults.

Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification. See [How to create OAuth2 credentials for Google Apps](https://devcaster.dev/auth/googleapps).

### Why am I getting "Google Maps API has not been used in project" error?

When using custom OAuth credentials, the Google Maps API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.

### Why am I getting "Error 400: invalid_scope"?

The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/auth-configuration/programmatic-auth-configs).

### Why does the OAuth consent screen show "Devcaster" instead of my app?

By default, the consent screen uses Devcaster's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).

### Why am I getting 401 errors on tool calls?

The user's access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google's refresh token limit (~50 per account) was exceeded. Re-authenticating the user typically resolves this.

---

## Tools

### Autocomplete Place Predictions

**Slug:** `GOOGLE_MAPS_AUTOCOMPLETE`

Returns place and query predictions for text input. Use when implementing as-you-type autocomplete functionality for place searches. Returns up to five predictions ordered by relevance.

### Compute Route Matrix

**Slug:** `GOOGLE_MAPS_COMPUTE_ROUTE_MATRIX`

Calculates travel distance and duration matrix between multiple origins and destinations using the modern Routes API; supports OAuth2 authentication and various travel modes.

### Distance Matrix (Legacy)

**Slug:** `GOOGLE_MAPS_DISTANCE_MATRIX_API`

DEPRECATED: Legacy API that calculates travel distance and time for a matrix of origins and destinations. This API only works with API keys (no OAuth2 support). Use the modern 'Compute Route Matrix' action instead, which supports OAuth2 authentication. Supports different modes of transportation and options like departure/arrival times.

### Geocode Address

**Slug:** `GOOGLE_MAPS_GEOCODE_ADDRESS`

DEPRECATED: Legacy API to convert street addresses into geographic coordinates (latitude and longitude). This API works best with API key authentication. For OAuth connections without an API key, you may need to provide the 'key' parameter or use the newer 'Text Search' action instead. Use when you need to geocode an address or location to get its precise latitude/longitude coordinates.

### Geocode Address With Query

**Slug:** `GOOGLE_MAPS_GEOCODE_ADDRESS_WITH_QUERY`

Tool to map addresses to geographic coordinates with query parameter. Use when you need to convert a textual address into latitude/longitude coordinates using the modern v4beta API.

### Geocode Destinations

**Slug:** `GOOGLE_MAPS_GEOCODE_DESTINATIONS`

Tool to perform destination lookup and return detailed destination information including primary place, containing places, sub-destinations, landmarks, entrances, and navigation points. Use when you need comprehensive destination data for an address, place ID, or geographic coordinates.

### Reverse Geocode Location

**Slug:** `GOOGLE_MAPS_GEOCODE_LOCATION`

Tool to convert geographic coordinates (latitude and longitude) to human-readable addresses using reverse geocoding. Use when you need to find the address or place name for a given set of coordinates.

### Reverse Geocode Location With Query

**Slug:** `GOOGLE_MAPS_GEOCODE_LOCATION_WITH_QUERY`

Tool to convert geographic coordinates to human-readable addresses using a location query parameter. Use when you need reverse geocoding with coordinates in a single string format.

### Geocode Place by ID

**Slug:** `GOOGLE_MAPS_GEOCODE_PLACE`

Tool to perform geocode lookup using a place identifier to retrieve address and coordinates. Use when you need to get detailed geographic information for a specific Google Place ID.

### Geocoding API

**Slug:** `GOOGLE_MAPS_GEOCODING_API`

Convert addresses into geographic coordinates (latitude and longitude) and vice versa (reverse geocoding), or get an address for a Place ID. Uses the Geocoding API v4 (v4beta) which supports OAuth2 authentication.

### Geolocate Device

**Slug:** `GOOGLE_MAPS_GEOLOCATE`

Tool to determine location based on cell towers and WiFi access points. Use when you need to find the geographic location of a device using network infrastructure data.

### Get 2D Map Tile

**Slug:** `GOOGLE_MAPS_GET2D_TILE`

Tool to retrieve a 2D map tile image at specified coordinates for building custom map visualizations. Use when you need to download individual map tile images for roadmap, satellite, or terrain views. Requires a valid session token from the createSession endpoint.

### Get 3D Tiles Root

**Slug:** `GOOGLE_MAPS_GET3D_TILES_ROOT`

Tool to retrieve the 3D Tiles tileset root configuration for photorealistic 3D map rendering. Use when you need to initialize a 3D renderer with Google's photorealistic tiles following the OGC 3D Tiles specification.

### Get Directions

**Slug:** `GOOGLE_MAPS_GET_DIRECTION`

Fetches detailed directions between an origin and a destination, supporting intermediate waypoints and various travel modes. Automatically uses the modern Routes API with OAuth2 when available, falling back to legacy API with API key if provided.

### Get Place Details

**Slug:** `GOOGLE_MAPS_GET_PLACE_DETAILS`

Retrieves comprehensive details for a place using its resource name (places/{place_id} format). Use when you need detailed information about a specific place.

### Get Route

**Slug:** `GOOGLE_MAPS_GET_ROUTE`

Calculates one or more routes between two specified locations. Uses various travel modes and preferences; addresses must be resolvable by Google Maps.

### Embed Google Map

**Slug:** `GOOGLE_MAPS_MAPS_EMBED_API`

Tool to generate an embeddable Google Map URL and HTML iframe code. Use when you need to display a map (place, view, directions, street view, search) on a webpage without JavaScript. Note: This API only works with API keys (no OAuth2 support). It generates embed URLs and does not make direct API calls.

### Nearby search

**Slug:** `GOOGLE_MAPS_NEARBY_SEARCH`

Searches for places (e.g., restaurants, parks) within a specified circular area, with options to filter by place types and customize the returned fields and number of results.

### Get Place Photo

**Slug:** `GOOGLE_MAPS_PLACE_PHOTO`

Retrieves high quality photographic content from the Google Maps Places database. Use when you need to download a place photo using a photo_reference obtained from Place Details, Nearby Search, or Text Search requests. Images are scaled proportionally to fit within specified dimensions.

### Text Search

**Slug:** `GOOGLE_MAPS_TEXT_SEARCH`

Searches for places on Google Maps using a textual query (e.g., "restaurants in London", "Eiffel Tower").

### Create Tiles Session

**Slug:** `GOOGLE_MAPS_TILES_CREATE_SESSION`

Tool to create a session token required for accessing 2D Tiles and Street View imagery. Use when you need to initialize tile-based map rendering or street view display. The session token is valid for approximately two weeks and must be included in all subsequent tile requests.
