Grounding with Google Maps in Vertex AI

European Economic Area (EEA) developers

Grounding with Google Maps in Vertex AI combines the power of Gemini with Google Maps, which has access to information on over 250 million places. This important integration that's available through Vertex AI is designed to help you create a new generation of generative applications.

This page explains how you can use Google Maps to ground your LLM responses.

Overview

Grounding with Google Maps in Vertex AI is a service that lets you use Google Maps data with LLMs to provide more accurate and context-aware responses to your prompts. Grounding with Google Maps is integrated with Vertex AI to support your use of geographical data with your Gemini model.

Grounding with Google Maps helps you to discover new places, plan for events, and get recommendations for a variety of locations. You can do the following:

  • Ask a conversational assistant about the area and any nearby places. Your assistant has access to the travel time information and can let you know how far a place is from your location. For example, Are there any parks nearby?
  • See personalized descriptions of the place that matches your criteria. For example, Can you tell me more about the parks and any family-friendly restaurants that are within a walkable distance?

Grounding with Google Maps lets you create generative AI applications from an LLM-powered chat using geospatial context to generate a personalized location-based summary to help you make better decisions.

For assistance, send a message to maps-grounding-feedback-external@google.com.

Supported models

This section lists the models that support grounding with Google Maps.

For more information about the Gemini models, see Gemini models.

Access to Grounding with Google Maps

To use Grounding with Google Maps in Vertex AI, follow these steps:

  1. To request access to use Grounding with Google Maps in Vertex AI for specific projects, complete and submit the Opt-in or Opt-out to use Google Maps form.

    This form requires your email address, company name, project ID, and your acceptance of the terms.

  2. If you don't have a project, see Creating and managing projects.

  3. In the Google Cloud console, go to the Maps Grounding API page.

    Go to Maps Grounding API

    To enable the Maps Grounding API, click Enable. Select a project, and the Maps Grounding API page displays.

  4. In the Google Cloud console, go to the Maps JavaScript API page.

    Go to Maps JavaScript API

    To enable JavaScript, click Enable. Select a project, and the APIs & Services page displays.

  5. To verify that Google Maps is enabled, go to Vertex AI Studio.

    Go to Vertex AI Studio

    1. Select the project that you enabled the APIs for.

    2. To turn on the Google Maps feature in the Tools section of the model's pane, click the Grounding: Google toggle.

    3. Select Google Maps Preview.

    4. Enter the API Key.

      1. If you don't have an API Key, see Creating API keys.
      2. Limit use of the APIs by Restricting API keys.

    5. Select the Location for a location-based response.

    6. Click Apply.

Place properties

This section lists place properties that are used to describe locations and used by Grounding with Google Maps to generate responses. These properties are used to determine the types of questions that Grounding with Google Maps can answer.

Sample place properties

This list provides an alphabetized sampling of properties about places that might be used by your model to generate responses.

  • Address
  • Cash only
  • Credit card
  • Curbside pickup
  • Debit card
  • Distance
  • Free parking lot
  • Live music
  • Menu for children
  • Opening hours
  • Pet friendly
  • Serves beer
  • Serves vegetarian food
  • Wheelchair accessible
  • Wifi

Examples of using place properties

The following examples use place properties in questions about different types of places. Grounding with Google Maps uses the properties to understand your intent and then provides relevant answers based on the data associated with places in Google Maps.

  • Plan a family dinner: You might ask, Is "The Italian Place" good for children, and do they offer takeout? What is their rating?

    Answers to these questions help you to determine if a restaurant is suitable for a family and if the restaurant offers a convenient service.

  • Check accessibility for a friend: You might ask, I need a restaurant that has a wheelchair accessible entrance.

    A response to this prompt might help you to determine if the location meets specific accessibility needs.

  • Find a location for a late-night snack: You might ask, Is "Burger Joint" open now? Do they serve dinner? What are their opening hours for Friday?

    Answers to these questions help you to find an open establishment serving a specific meal during a particular time.

  • Meet a client for coffee: You might ask, Does "Cafe Central" have Wifi? Do they serve coffee? What is their price level, and do they accept credit cards?

    Answers to these questions help you to assess the suitability of a cafe for a business meeting based on amenities, offerings, and payment options.

Use Grounding with Google Maps to ground your model

You can use the Google Maps API to ground your model's responses.

These code samples demonstrate how to use the Maps API to ground your model's responses using Grounding with Google Maps.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    ApiKeyConfig,
    AuthConfig,
    GenerateContentConfig,
    GoogleMaps,
    HttpOptions,
    Tool,
)

# TODO(developer): Update below line with your Google Maps API key
GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY"

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Recommend a good restaurant in San Francisco.",
    config=GenerateContentConfig(
        tools=[
            # Use Google Maps Tool
            Tool(
                google_maps=GoogleMaps(
                    auth_config=AuthConfig(
                        api_key_config=ApiKeyConfig(
                            api_key_string=GOOGLE_MAPS_API_KEY,
                        )
                    )
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'San Francisco boasts a vibrant culinary scene...'

REST

Before using any of the request data, make the following replacements:

  • LOCATION: The region to process the request.
  • PROJECT_ID: Your project ID.
  • MODEL_ID: The model ID of the multimodal model.
  • TEXT: The text instructions to include in the prompt.
  • API_KEY: Your API key.
  • LATITUDE: The latitude of the location.
  • LONGITUDE: The longitude of the location.

HTTP method and URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

Request JSON body: 

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleMaps": {
      "authConfig": {
        "apiKeyConfig": {
          "apiKeyString": "API_KEY"
        }
      }
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Here are a few options for late-night burgers in San Jose, based on the search results. Keep in mind that \"late night\" can be subjective, so I've included places with varying closing times. I recommend double-checking their hours before you go, as these can change.\n\n*   **Campus Burgers:** Open until 12:00 AM every night except Sunday (closed).\n*   **Lazy Dog Restaurant & Bar:** Open until 12:00 AM every night.\n*   **Dough Burger:** Open until 1:30 AM Monday through Thursday and Sunday, and until 3:00 AM on Friday and Saturday.\n*   **El Apartamento Colombian Burgers:** Open until 1:00 AM on Friday and Saturday, and until 10:30 PM Monday through Wednesday and until 11:00 PM Thursday and Sunday.\n*   **Paper Plane:** Open until 2:00 AM Thursday through Saturday, and until 12:00 AM on Tuesday and Wednesday and Sunday. Closed on Monday.\n\nNote that opening hours are subject to change.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "retrievalQueries": [
          "late night burger san jose"
        ],
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=15700677770979677665",
              "title": "El Apartamento Colombian Burgers",
              "text": "**About:**\n\n* **Type:** Hamburger Restaurant\n* **Address:** 76 E Santa Clara St, San Jose, CA 95113, USA\n* **Open Now:** No\n* **Rating:** 4.9 (25 reviews)\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Outdoor Seating:** No\n* **Live Music:** No\n* **Curbside Pickup:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 5:00 – 10:30 PM\n* Tuesday: 5:00 – 10:30 PM\n* Wednesday: 5:00 – 10:30 PM\n* Thursday: 4:00 – 11:00 PM\n* Friday: 4:00 PM – 1:00 AM\n* Saturday: 4:00 PM – 1:00 AM\n* Sunday: 4:00 – 11:00 PM\n\n**Parking options:**\n\n* **Free street parking:** Yes\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible entrance:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Cash Only:** No\n\n**Distance & Travel Time:**\n\n* 4733.0 kilometers\n* 43.4 hours"
            }
          },
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=8798666889278262772",
              "title": "Campus Burgers",
              "text": "**About:**\n\n* **Type:** Hamburger Restaurant\n* **Address:** 108 Paseo de San Antonio, San Jose, CA 95113, USA\n* **Open Now:** Yes\n* **Rating:** 4.4 (207 reviews)\n* **Price Level:** Inexpensive\n* **Phone:** (408) 352-5507\n* **Additional Summary:** Simple hamburger restaurant with a limited menu of comfort fare such as burgers and fries.\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Good for Groups:** Yes\n* **Outdoor Seating:** Yes\n* **Live Music:** No\n* **Menu for Children:** No\n* **Serves Cocktails:** No\n* **Serves Dessert:** Yes\n* **Serves Coffee:** No\n* **Good for Watching Sports:** No\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 11:00 AM – 12:00 AM\n* Tuesday: 11:00 AM – 12:00 AM\n* Wednesday: 11:00 AM – 12:00 AM\n* Thursday: 11:00 AM – 12:00 AM\n* Friday: 11:00 AM – 12:00 AM\n* Saturday: 11:00 AM – 12:00 AM\n* Sunday: Closed\n\n**Parking options:**\n\n* **Paid parking lot:** Yes\n* **Free street parking:** Yes\n* **Paid street parking:** Yes\n* **Valet parking:** No\n* **Paid garage parking:** Yes\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible entrance:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Debit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 4732.5 kilometers\n* 43.4 hours"
            }
          },
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=3915125089239094417",
              "title": "Paper Plane",
              "text": "**About:**\n\n* **Type:** Bar\n* **Address:** 72 S 1st St, San Jose, CA 95113, USA\n* **Open Now:** No\n* **Rating:** 4.4 (2452 reviews)\n* **Price Level:** Moderate\n* **Phone:** (408) 713-2625\n* **Summary:** Relaxed spot with a long bar in an exposed brick space for creative or classic cocktails & snacks.\n* **Additional Summary:** Casual, popular bar serving signature cocktails and New American fare, including burgers and tacos.\n* **Takes Reservations:** Yes\n* **Offers Takeout:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** No\n* **Allows Dogs:** No\n* **Has Restroom:** Yes\n* **Good for Groups:** Yes\n* **Outdoor Seating:** No\n* **Live Music:** No\n* **Serves Cocktails:** Yes\n* **Good for Watching Sports:** No\n* **Serves Beer:** Yes\n* **Serves Wine:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: Closed\n* Tuesday: 5:00 PM – 12:00 AM\n* Wednesday: 5:00 PM – 12:00 AM\n* Thursday: 5:00 PM – 2:00 AM\n* Friday: 5:00 PM – 2:00 AM\n* Saturday: 5:00 PM – 2:00 AM\n* Sunday: 5:00 PM – 12:00 AM\n\n**Parking options:**\n\n* **Paid parking lot:** Yes\n* **Free street parking:** Yes\n* **Paid street parking:** Yes\n* **Valet parking:** No\n* **Paid garage parking:** Yes\n\n**Accessibility:**\n\n* **Wheelchair accessible entrance:** Yes\n* **Wheelchair accessible restroom:** Yes\n* **Wheelchair accessible seating:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 4733.0 kilometers\n* 43.4 hours"
            }
          },
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=12662287798905863411",
              "title": "Lazy Dog Restaurant & Bar",
              "text": "**About:**\n\n* **Type:** American Restaurant\n* **Address:** 5305 Almaden Expy, San Jose, CA 95118, USA\n* **Open Now:** Yes\n* **Rating:** 4.2 (940 reviews)\n* **Price Level:** Moderate\n* **Phone:** (408) 786-9594\n* **Summary:** Relaxed, lodge-chic chain serving global comfort fare, including stir-fries, pot roast & pastas.\n* **Additional Summary:** American food including comfort fare and small plates served in a casual setting with a bar.\n* **Takes Reservations:** Yes\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Allows Dogs:** Yes\n* **Has Restroom:** Yes\n* **Good for Groups:** Yes\n* **Outdoor Seating:** Yes\n* **Live Music:** No\n* **Menu for Children:** Yes\n* **Serves Cocktails:** Yes\n* **Serves Dessert:** Yes\n* **Serves Coffee:** Yes\n* **Has Wifi:** Yes\n* **Good for Watching Sports:** Yes\n* **Curbside Pickup:** Yes\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n* **Serves Beer:** Yes\n* **Serves Wine:** Yes\n* **Serves Brunch:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 11:00 AM – 12:00 AM\n* Tuesday: 11:00 AM – 12:00 AM\n* Wednesday: 11:00 AM – 12:00 AM\n* Thursday: 11:00 AM – 12:00 AM\n* Friday: 11:00 AM – 12:00 AM\n* Saturday: 10:00 AM – 12:00 AM\n* Sunday: 10:00 AM – 12:00 AM\n\n**Parking options:**\n\n* **Free parking lot:** Yes\n* **Free street parking:** Yes\n* **Valet parking:** No\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible entrance:** Yes\n* **Wheelchair accessible restroom:** Yes\n* **Wheelchair accessible seating:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Debit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 4745.7 kilometers\n* 43.5 hours"
            }
          },
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=12520445715080978741",
              "title": "Dough Burger",
              "text": "**About:**\n\n* **Type:** Restaurant\n* **Address:** 1721 Old Bayshore Hwy, San Jose, CA 95112, USA\n* **Open Now:** No\n* **Rating:** 4.2 (61 reviews)\n* **Phone:** (408) 515-0161\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Live Music:** No\n* **Curbside Pickup:** Yes\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 6:00 PM – 1:30 AM\n* Tuesday: 6:00 PM – 1:30 AM\n* Wednesday: 6:00 PM – 1:30 AM\n* Thursday: 6:00 PM – 1:30 AM\n* Friday: 6:00 PM – 3:00 AM\n* Saturday: 6:00 PM – 3:00 AM\n* Sunday: 6:00 PM – 1:30 AM\n\n**Parking options:**\n\n* **Free parking lot:** Yes\n* **Free street parking:** Yes\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible entrance:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Cash Only:** No\n\n**Distance & Travel Time:**\n\n* 4740.1 kilometers\n* 43.3 hours"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 267,
              "endIndex": 346,
              "text": "*   **Campus Burgers:** Open until 12:00 AM every night except Sunday (closed)."
            },
            "groundingChunkIndices": [
              1
            ],
            "confidenceScores": [
              0.76444983
            ]
          }
        ],
        "googleMapsWidgetContextToken": "widgetcontent/AcBXPQfo6pGrCXPJeN2xtADMw1TPz8Wzwm-..."
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 7,
    "candidatesTokenCount": 236,
    "totalTokenCount": 243,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 7
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 236
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-04-03T20:11:51.118341Z"
}
```

Render the Google Maps contextual widget

Rendering the Google Maps contextual widget is required as part of using Grounding with Google Maps in Vertex AI. In any response that is grounded with Google Maps, there is a corresponding googleMapsWidgetContextToken that is used to render the contextual widget in close proximity to the generated response.

  "googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
  Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",

Your page that displays the widget must use the alpha version of the Google Maps JS API. For more information, see Load the Maps JavaScript API.

You must use the API key that was enabled for Grounding with Google Maps in Vertex AI to load the Google Maps JS API.

This code sample demonstrates how to create a widget using HTML.

  <body>
    <gmp-place-contextual id="widget"></gmp-place-contextual>
  </body>

In your Javascript, use the following method to update the context token:

function updateWidget(contextToken) {
  let widget = document.querySelector('#widget');
  widget.contextToken = contextToken;
}

You can also create a widget dynamically with the following code:

async function createWidget(contextToken) {
  await google.maps.importLibrary('places');
  let widgetContainer = document.querySelector('#wc');  // a div that contains the widget
  const placeContextualElement = new
      google.maps.places.PlaceContextualElement({ contextToken });
  widgetContainer.appendChild(placeContextualElement);
}

This HTML code sample demonstrates how to use configuration options to toggle between two different layouts (compact or vertical).

    <gmp-place-contextual id="widget">
      <gmp-place-contextual-list-config layout="compact">
      </gmp-place-contextual-list-config>
    </gmp-place-contextual>

This HTML code sample demonstrates how to disable the map.

    <gmp-place-contextual id="widget">
      <gmp-place-contextual-list-config map-hidden>
      </gmp-place-contextual-list-config>
    </gmp-place-contextual>

This JavaScript code sample demonstrates how to specify a compact layout and how to hide the map.

  const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    layout: 'compact',
    mapHidden: true
  });
  widget.appendChild(widgetConfig);

What's next

  • To learn more about how to ground Gemini models to your data, see Grounding with your data.
  • To learn more about responsible AI best practices and Vertex AI's safety filters, see Responsible AI.