Cómo realizar la puesta a tierra con Google Maps

La fundamentación con Google Maps conecta las capacidades generativas de Gemini con los datos enriquecidos, fácticos y actualizados de Google Maps. Esta función permite a los desarrolladores incorporar fácilmente la funcionalidad que tiene en cuenta la ubicación en sus aplicaciones. Cuando una búsqueda del usuario tiene un contexto relacionado con los datos de Maps, el modelo de Gemini aprovecha Google Maps para proporcionar respuestas precisas y actualizadas que son pertinentes para la ubicación especificada por el usuario o el área general.

  • Respuestas precisas y basadas en la ubicación: Aprovecha los datos extensos y actuales de Google Maps para las búsquedas específicas de una ubicación geográfica.
  • Personalización mejorada: Adapta las recomendaciones y la información según las ubicaciones proporcionadas por el usuario.
  • Información contextual y widgets: Tokens contextuales para renderizar widgets interactivos de Google Maps junto con el contenido generado.

Comenzar

En este ejemplo, se muestra cómo integrar Fundamentación con Google Maps en tu aplicación para proporcionar respuestas precisas y basadas en la ubicación a las preguntas de los usuarios. La instrucción solicita recomendaciones locales con una ubicación del usuario opcional, lo que permite que el modelo de Gemini use los datos de Google Maps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

Cómo funciona la fundamentación con Google Maps

La Fundamentación con Google Maps integra la API de Gemini con el ecosistema geográfico de Google a través de la API de Google Maps como fuente de fundamentación. Cuando la búsqueda de un usuario contiene contexto geográfico, el modelo de Gemini puede invocar la herramienta de Fundamentación con Google Maps. Luego, el modelo puede generar respuestas fundamentadas en los datos de Google Maps que sean pertinentes para la ubicación proporcionada.

Por lo general, el proceso incluye lo siguiente:

  1. Búsqueda del usuario: Un usuario envía una búsqueda a tu aplicación, que puede incluir contexto geográfico (p.ej., "cafeterías cerca de mí", "museos en San Francisco").
  2. Invocación de la herramienta: El modelo de Gemini, que reconoce la intención geográfica, invoca la herramienta de Fundamentación con Google Maps. De manera opcional, se puede proporcionar a esta herramienta el latitude y el longitude del usuario. La herramienta es de búsqueda textual y se comporta de manera similar a la búsqueda en Maps, ya que las búsquedas locales ("cerca de mí") usarán las coordenadas, mientras que es poco probable que las búsquedas específicas o no locales se vean influenciadas por la ubicación explícita.
  3. Recuperación de datos: El servicio de Fundamentación con Google Maps consulta Google Maps para obtener información pertinente (p.ej., lugares, opiniones, fotos, direcciones y horarios de atención).
  4. Generación fundamentada: Los datos recuperados de Maps se usan para fundamentar la respuesta del modelo de Gemini, lo que garantiza la precisión fáctica y la relevancia.
  5. Respuesta y anotaciones: El modelo devuelve una respuesta de texto con anotaciones intercaladas que vinculan a fuentes de Google Maps, lo que permite a los desarrolladores mostrar citas y, de manera opcional, renderizar un widget contextual de Google Maps.

Por qué y cuándo usar la Fundamentación con Google Maps

La fundamentación con Google Maps es ideal para las aplicaciones que requieren información precisa, actualizada y específica de la ubicación. Mejora la experiencia del usuario, ya que proporciona contenido pertinente y personalizado respaldado por la extensa base de datos de Google Maps, que incluye más de 250 millones de lugares en todo el mundo.

Debes usar la fundamentación con Google Maps cuando tu aplicación necesite hacer lo siguiente:

  • Proporciona respuestas completas y precisas a preguntas específicas de la ubicación geográfica.
  • Crea planificadores de viajes y guías locales conversacionales.
  • Recomendar lugares de interés según la ubicación y las preferencias del usuario, como restaurantes o tiendas
  • Crea experiencias que tengan en cuenta la ubicación para servicios de redes sociales, venta minorista o entrega de comida.

La fundamentación con Google Maps se destaca en los casos de uso en los que la proximidad y los datos fácticos actuales son fundamentales, como encontrar la "mejor cafetería cerca de mí" o recibir indicaciones para llegar.

Casos de uso

La fundamentación con Google Maps admite una variedad de casos de uso que tienen en cuenta la ubicación.

Cómo controlar las preguntas específicas de un lugar

Haz preguntas detalladas sobre un lugar específico para obtener respuestas basadas en las opiniones de los usuarios de Google y otros datos de Maps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

Proporcionar personalización basada en la ubicación

Obtener recomendaciones personalizadas según las preferencias de un usuario y un área geográfica específica

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

Ayuda con la planificación de itinerarios

Genera planes de varios días con instrucciones sobre cómo llegar e información sobre varias ubicaciones, lo que resulta ideal para aplicaciones de viajes.

Python

from google import genai

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.',
    tools: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476,
      enableWidget: true
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476,
      "enable_widget": true
    }]
  }'

Requisitos de uso del servicio

En esta sección, se describen los requisitos de uso del servicio de Grounding con Google Maps.

Informa al usuario sobre el uso de las fuentes de Google Maps

Con cada resultado fundamentado de Google Maps, recibirás anotaciones de la fuente en los bloques de contenido del paso model_output que respaldan cada respuesta. Se devuelven los siguientes metadatos:

  • URL de origen
  • nombre

Cuando presentes resultados de la fundamentación con Google Maps, debes especificar las fuentes asociadas de Google Maps y comunicarles a los usuarios lo siguiente:

  • Las fuentes de Google Maps deben aparecer inmediatamente después del contenido generado que admiten. Este contenido generado también se conoce como Resultado Fundamentado de Google Maps.
  • Las fuentes de Google Maps deben poder verse en una sola interacción del usuario.

Mostrar fuentes de Google Maps con vínculos de Google Maps

Para cada anotación de fuente, se debe generar una vista previa del vínculo según los siguientes requisitos:

  • Atribuye cada fuente a Google Maps según los lineamientos de atribución de texto de Google Maps.
  • Muestra el nombre de la fuente proporcionado en la respuesta.
  • Vincula la fuente con el url de la anotación.

Lineamientos para la atribución de texto de Google Maps

Cuando atribuyas fuentes a Google Maps en texto, sigue estos lineamientos:

  • No modifiques el texto de Google Maps de ninguna manera:
    • No cambies el uso de mayúsculas en Google Maps.
    • No dividas Google Maps en varias líneas.
    • No localices Google Maps en otro idioma.
    • Evita que los navegadores traduzcan Google Maps usando el atributo HTML translate="no".

Para obtener más información sobre algunos de nuestros proveedores de datos de Google Maps y sus condiciones de licencia, consulta los avisos legales de Google Maps y Google Earth.

Prácticas recomendadas

  • Proporciona la ubicación del usuario: Para obtener las respuestas más relevantes y personalizadas, siempre incluye latitude y longitude en la configuración de tu herramienta google_maps cuando se conozca la ubicación del usuario.
  • Renderiza el widget contextual de Google Maps: El widget contextual se renderiza con el token de contexto, google_maps_widget_context_token, que se devuelve en la respuesta de la API de Gemini y se puede usar para renderizar contenido visual de Google Maps.
  • Informa a los usuarios finales: Informa claramente a tus usuarios finales que se usan datos de Google Maps para responder sus preguntas, en especial cuando la herramienta está habilitada.
  • Desactivar cuando no sea necesario: La fundamentación con Google Maps está desactivada de forma predeterminada. Solo habilítalo ("tools": [{"type": "google_maps"}]) cuando una búsqueda tenga un contexto geográfico claro para optimizar el rendimiento y el costo.

Limitaciones

  • Actualmente, la fundamentación con Google Maps solo admite instrucciones y respuestas en inglés.
  • Es posible que la herramienta no esté disponible en todas las regiones.
  • Los resultados pueden variar según la precisión de la ubicación y los datos disponibles de Maps.
  • Alcance geográfico: La fundamentación con Google Maps está disponible a nivel mundial.
  • Estado predeterminado: La herramienta Fundamentación con Google Maps está desactivada de forma predeterminada. Debes habilitarlo de forma explícita en tus solicitudes a la API.

Precios y límites de frecuencia

La fundamentación con los precios de Google Maps se basa en las búsquedas. La tarifa actual es de USD 25 por cada 1,000 instrucciones fundamentadas. El nivel gratuito también tiene hasta 500 solicitudes por día disponibles. Una solicitud solo se contabiliza para la cuota cuando una instrucción devuelve correctamente al menos un resultado fundamentado de Google Maps (es decir, resultados que contienen al menos una fuente de Google Maps). Si se envían varias búsquedas a Google Maps desde una sola solicitud, se contabiliza como una solicitud para el límite de frecuencia.

Para obtener información detallada sobre los precios, consulta la página de precios de la API de Gemini.

Modelos compatibles

Los siguientes modelos admiten la fundamentación con Google Maps:

Modelo Fundamentación con Google Maps
Versión preliminar de Gemini 3.1 Pro ✔️
Gemini 3.1 Flash-Lite ✔️
Versión preliminar de Gemini 3.1 Flash-Lite ✔️
Versión preliminar de Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Combinaciones de herramientas compatibles

Los modelos de Gemini 3 admiten la combinación de herramientas integradas (como la fundamentación con Google Maps) con herramientas personalizadas (llamadas a funciones). Obtén más información en la página de combinaciones de herramientas.

¿Qué sigue?