Embasamento com o Google Maps na Vertex AI

O embasamento com o Google Maps na Vertex AI combina o poder do Gemini com o Google Maps, que tem acesso a informações sobre mais de 250 milhões de lugares. Essa integração importante, disponível na Vertex AI, foi projetada para ajudar você a criar uma nova geração de aplicativos generativos.

Nesta página, explicamos como usar o Google Maps para fundamentar as respostas do LLM.

Visão geral

O embasamento com o Google Maps na Vertex AI é um serviço que permite usar dados do Google Maps com LLMs para fornecer respostas mais precisas e contextualizadas aos seus comandos. O embasamento com o Google Maps está integrado à Vertex AI para oferecer suporte ao uso de dados geográficos com seu modelo do Gemini.

Com o Google Maps, você descobre novos lugares, planeja eventos e recebe recomendações de vários locais. Faça o seguinte:

  • Pergunte a um assistente de conversa sobre a área e os lugares próximos. O assistente tem acesso às informações de tempo de viagem e pode informar a distância de um lugar até sua localização. Por exemplo, Tem algum parque por perto?
  • Confira descrições personalizadas do lugar que corresponde aos seus critérios. Por exemplo, Você pode me dar mais informações sobre os parques e restaurantes familiares que ficam a uma distância caminhável?

Com o Grounding com o Google Maps, você cria aplicativos de IA generativa em um chat com tecnologia de LLM usando o contexto geoespacial para gerar um resumo personalizado com base na localização e ajudar você a tomar decisões melhores.

Para receber ajuda, envie uma mensagem para maps-grounding-feedback-external@google.com.

Modelos compatíveis

Esta seção lista os modelos que oferecem suporte ao embasamento com o Google Maps.

Para mais informações sobre os modelos do Gemini, consulte Modelos do Gemini.

Acesso ao embasamento com o Google Maps

Para usar o Embasamento com o Google Maps na Vertex AI, siga estas etapas:

  1. Para solicitar acesso ao uso do embasamento com o Google Maps na Vertex AI em projetos específicos, preencha e envie o formulário de ativação ou desativação do uso do Google Maps.

    Nesse formulário, você precisa informar seu endereço de e-mail, nome da empresa, ID do projeto e aceitar os termos.

  2. Se você não tiver um projeto, consulte Como criar e gerenciar projetos.

  3. No console Google Cloud , acesse a página API Maps Grounding.

    Acessar a API Maps Grounding

    Para ativar a API Maps Grounding, clique em Ativar. Selecione um projeto. A página da API Maps Grounding vai aparecer.

  4. No console Google Cloud , acesse a página API Maps JavaScript.

    Acesse a API Maps JavaScript

    Para ativar o JavaScript, clique em Ativar. Selecione um projeto. A página APIs e serviços vai aparecer.

  5. Para verificar se o Google Maps está ativado, acesse o Vertex AI Studio.

    Acessar o Vertex AI Studio

    1. Selecione o projeto em que você ativou as APIs.

    2. Para ativar o recurso do Google Maps na seção Ferramentas do painel do modelo, clique na chave Fundamentação: Google.

    3. Selecione Prévia do Google Maps.

    4. Insira a chave de API.

      1. Se você não tiver uma chave de API, consulte Como criar chaves de API.
      2. Limite o uso das APIs restringindo as chaves de API.

    5. Selecione o Local para uma resposta com base na localização.

    6. Clique em Aplicar.

Propriedades do lugar

Esta seção lista as propriedades de lugar usadas para descrever locais e usadas pelo Grounding com o Google Maps para gerar respostas. Essas propriedades são usadas para determinar os tipos de perguntas que o Grounding com o Google Maps pode responder.

Exemplo de propriedades de lugar

Esta lista fornece uma amostra em ordem alfabética de propriedades sobre lugares que podem ser usadas pelo seu modelo para gerar respostas.

  • Endereço
  • Aceita somente dinheiro
  • Cartão de crédito
  • Retirada
  • Cartão de débito
  • Distância
  • Estacionamento gratuito
  • Música ao vivo
  • Menu infantil
  • Horário de funcionamento
  • Aceita animais de estimação
  • Serve cerveja
  • Serve comida vegetariana
  • Acessibilidade para cadeirantes
  • Wi-Fi

Exemplos de uso de propriedades de lugar

Os exemplos a seguir usam propriedades de lugar em perguntas sobre diferentes tipos de lugares. A fundamentação com o Google Maps usa as propriedades para entender sua intenção e fornecer respostas relevantes com base nos dados associados a lugares no Google Maps.

  • Planejar um jantar em família: você pode perguntar: O restaurante "The Italian Place" é bom para crianças? Eles oferecem comida para viagem? Qual é a classificação deles?

    As respostas a essas perguntas ajudam a determinar se um restaurante é adequado para uma família e se ele oferece um serviço conveniente.

  • Verificar a acessibilidade para um amigo: você pode perguntar: Preciso de um restaurante que tenha uma entrada acessível para cadeirantes.

    Uma resposta a esse comando pode ajudar você a determinar se o local atende a necessidades específicas de acessibilidade.

  • Encontrar um lugar para comer um lanche tarde da noite: você pode perguntar: O "Burger Joint" está aberto agora? Eles servem jantar? Qual é o horário de funcionamento na sexta-feira?

    As respostas a essas perguntas ajudam você a encontrar um estabelecimento aberto que sirva uma refeição específica em um determinado horário.

  • Encontrar um cliente para tomar um café: você pode perguntar: O "Café Central" tem Wi-Fi? Eles servem café? Qual é o nível de preços e eles aceitam cartões de crédito?

    As respostas a essas perguntas ajudam a avaliar a adequação de um café para uma reunião de negócios com base nas comodidades, nas ofertas e nas opções de pagamento.

Usar o embasamento com o Google Maps para embasar seu modelo

Você pode usar a API Google Maps para embasar as respostas do modelo.

Estes exemplos de código demonstram como usar a API Maps para embasar as respostas do modelo usando o embasamento com o Google Maps.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: a região para processar a solicitação.
  • PROJECT_ID: o ID do projeto.
  • MODEL_ID: o ID do modelo multimodal.
  • TEXT: as instruções de texto a serem incluídas no comando.
  • API_KEY: sua chave de API.
  • LATITUDE: a latitude do local.
  • LONGITUDE: a longitude do local.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "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"
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
}
```

Renderizar o widget contextual do Google Maps

A renderização do widget contextual do Google Maps é necessária como parte do uso do embasamento com o Google Maps na Vertex AI. Em qualquer resposta baseada no Google Maps, há um googleMapsWidgetContextToken correspondente usado para renderizar o widget contextual próximo à resposta gerada.

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

A página que mostra o widget precisa usar a versão Alfa da API Google Maps JavaScript. Para mais informações, consulte Carregar a API Maps JavaScript.

Use a chave de API ativada para o embasamento com o Google Maps na Vertex AI para carregar a API JavaScript do Google Maps.

Este exemplo de código demonstra como criar um widget usando HTML.

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

No JavaScript, use o seguinte método para atualizar o token de contexto:

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

Você também pode criar um widget dinamicamente com o seguinte código:

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);
}

Este exemplo de código HTML mostra como usar opções de configuração para alternar entre dois layouts diferentes (compact ou vertical).

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

Este exemplo de código HTML demonstra como desativar o mapa.

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

Este exemplo de código em JavaScript demonstra como especificar um layout de compact e como ocultar o mapa.

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

A seguir

  • Para saber mais sobre como embasar modelos do Gemini nos seus dados, consulte Embasamento com seus dados.
  • Para saber mais sobre as práticas recomendadas de IA responsável e os filtros de segurança da Vertex AI, consulte IA responsável.