Fundamentos con Google Maps en Vertex AI

La fundamentación con Google Maps en Vertex AI combina el poder de Gemini con Google Maps, que tiene acceso a información sobre más de 250 millones de lugares. Esta importante integración disponible a través de Vertex AI está diseñada para ayudarte a crear una nueva generación de aplicaciones generativas.

En esta página, se explica cómo puedes usar Google Maps para fundamentar las respuestas de tu LLM.

Descripción general

La fundamentación con Google Maps en Vertex AI es un servicio que te permite usar los datos de Google Maps con LLMs para proporcionar respuestas más precisas y contextuales a tus instrucciones. La fundamentación con Google Maps está integrada en Vertex AI para admitir el uso de datos geográficos con tu modelo de Gemini.

La fundamentación con Google Maps te ayuda a descubrir lugares nuevos, planificar eventos y obtener recomendaciones para una variedad de ubicaciones. Puedes realizar lo siguiente:

  • Pregúntale a un asistente conversacional sobre el área y los lugares cercanos. Tu asistente tiene acceso a la información del tiempo de viaje y puede informarte a qué distancia se encuentra un lugar de tu ubicación. Por ejemplo, ¿Hay parques cerca?
  • Ver descripciones personalizadas del lugar que coinciden con tus criterios Por ejemplo, ¿Me puedes dar más información sobre los parques y los restaurantes aptos para familias que se encuentran a una distancia a pie?

La fundamentación con Google Maps te permite crear aplicaciones de IA generativa a partir de un chat potenciado por un LLM que usa el contexto geoespacial para generar un resumen personalizado basado en la ubicación y ayudarte a tomar mejores decisiones.

Para obtener ayuda, envía un mensaje a maps-grounding-feedback-external@google.com.

Modelos compatibles

En esta sección, se enumeran los modelos que admiten la fundamentación con Google Maps.

Para obtener más información sobre los modelos de Gemini, consulta Modelos de Gemini.

Acceso a la fundamentación con Google Maps

Para usar la fundamentación con Google Maps en Vertex AI, sigue estos pasos:

  1. Para solicitar acceso al uso de la fundamentación con Google Maps en Vertex AI para proyectos específicos, completa y envía el formulario de aceptación o rechazo del uso de Google Maps.

    En este formulario, se requiere tu dirección de correo electrónico, el nombre de la empresa, el ID del proyecto y tu aceptación de las condiciones.

  2. Si no tienes un proyecto, consulta Crea y administra proyectos.

  3. En la consola de Google Cloud , ve a la página de la API de Maps Grounding.

    Ir a la API de Maps Grounding

    Para habilitar la API de Maps Grounding, haz clic en Habilitar. Selecciona un proyecto y se mostrará la página de la API de Maps Grounding.

  4. En la consola de Google Cloud , ve a la página de la API de Maps JavaScript.

    Ir a la API de Maps JavaScript

    Para habilitar JavaScript, haz clic en Habilitar. Selecciona un proyecto y se mostrará la página APIs y servicios.

  5. Para verificar que Google Maps esté habilitado, ve a Vertex AI Studio.

    Ir a Vertex AI Studio

    1. Selecciona el proyecto para el que habilitaste las APIs.

    2. Para activar la función de Google Maps en la sección Herramientas del panel del modelo, haz clic en el botón de activación Fundamentación: Google.

    3. Selecciona Vista previa de Google Maps.

    4. Ingresa la clave de API.

      1. Si no tienes una clave de API, consulta Cómo crear claves de API.
      2. Limita el uso de las APIs restringiendo las claves de API.

    5. Selecciona la ubicación para una respuesta basada en la ubicación.

    6. Haz clic en Aplicar.

Propiedades del lugar

En esta sección, se enumeran las propiedades de lugares que se usan para describir ubicaciones y que utiliza Grounding con Google Maps para generar respuestas. Estas propiedades se usan para determinar los tipos de preguntas que puede responder Grounding con Google Maps.

Ejemplo de propiedades de lugar

En esta lista, se proporciona una muestra alfabética de las propiedades sobre lugares que tu modelo podría usar para generar respuestas.

  • Dirección
  • Solo dinero en efectivo
  • Tarjeta de crédito
  • Retiros en la puerta
  • Tarjeta de débito
  • Distancia
  • Estacionamiento gratuito
  • Música en vivo
  • Menú para niños
  • Horario de atención
  • Se permiten mascotas
  • Ofrece cervezas
  • Ofrece comida vegetariana
  • Con acceso para silla de ruedas
  • Wi-Fi

Ejemplos de uso de las propiedades de lugar

En los siguientes ejemplos, se usan propiedades de lugares en preguntas sobre diferentes tipos de lugares. La fundamentación con Google Maps usa las propiedades para comprender tu intención y, luego, proporciona respuestas pertinentes basadas en los datos asociados con los lugares en Google Maps.

  • Planificar una cena familiar: Podrías preguntar: ¿"The Italian Place" es un buen lugar para niños y ofrece comida para llevar? ¿Cuál es su calificación?

    Las respuestas a estas preguntas te ayudan a determinar si un restaurante es adecuado para una familia y si ofrece un servicio conveniente.

  • Verificar la accesibilidad para un amigo: Podrías preguntar: Necesito un restaurante que tenga una entrada accesible para personas en silla de ruedas.

    Una respuesta a esta instrucción puede ayudarte a determinar si la ubicación satisface necesidades de accesibilidad específicas.

  • Buscar un lugar para comer un bocadillo a altas horas de la noche: Podrías preguntar: ¿"Burger Joint" está abierto ahora? ¿Sirven cena? ¿Cuál es el horario de atención del viernes?

    Las respuestas a estas preguntas te ayudan a encontrar un establecimiento abierto que sirva una comida específica en un momento determinado.

  • Reunirse con un cliente para tomar un café: Podrías preguntar: ¿"Café Central" tiene Wi-Fi? ¿Sirven café? ¿Cuál es su nivel de precios y si aceptan tarjetas de crédito?

    Las respuestas a estas preguntas te ayudan a evaluar la idoneidad de una cafetería para una reunión de negocios en función de los servicios, las ofertas y las opciones de pago.

Cómo usar la fundamentación con Google Maps para fundamentar tu modelo

Puedes usar la API de Google Maps para fundamentar las respuestas de tu modelo.

En estas muestras de código, se muestra cómo usar la API de Maps para fundamentar las respuestas de tu modelo con Grounding con Google Maps.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa con 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 cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La región para procesar la solicitud.
  • PROJECT_ID: El ID del proyecto.
  • MODEL_ID: El ID del modelo multimodal.
  • TEXT: Las instrucciones de texto que se incluirán en el mensaje.
  • API_KEY: Es tu clave de API.
  • LATITUDE: Es la latitud de la ubicación.
  • LONGITUDE: Es la longitud de la ubicación.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Renderiza el widget contextual de Google Maps

Es necesario renderizar el widget contextual de Google Maps como parte del uso de la fundamentación con Google Maps en Vertex AI. En cualquier respuesta que se base en Google Maps, hay un googleMapsWidgetContextToken correspondiente que se usa para renderizar el widget contextual cerca de la respuesta generada.

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

La página que muestra el widget debe usar la versión alfa de la API de Google Maps JavaScript. Para obtener más información, consulta Carga la API de Maps JavaScript.

Debes usar la clave de API que se habilitó para la fundamentación con Google Maps en Vertex AI para cargar la API de Maps JavaScript.

En esta muestra de código, se muestra cómo crear un widget con HTML.

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

En tu código JavaScript, usa el siguiente método para actualizar el token de contexto:

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

También puedes crear un widget de forma dinámica con el siguiente 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);
}

En este muestra de código HTML, se muestra cómo usar las opciones de configuración para alternar entre dos diseños diferentes (compact o vertical).

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

En esta muestra de código HTML, se muestra cómo inhabilitar el mapa.

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

En esta muestra de código de JavaScript, se muestra cómo especificar un diseño compact y cómo ocultar el mapa.

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

¿Qué sigue?

  • Para obtener más información sobre cómo fundamentar los modelos de Gemini con tus datos, consulta Fundamentación con tus datos.
  • Para obtener más información sobre las prácticas recomendadas de IA responsable y los filtros de seguridad de Vertex AI, consulta IA responsable.