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 que los desarrolladores incorporen fácilmente la funcionalidad basada en la ubicación a sus aplicaciones. Cuando una consulta del usuario tiene un contexto relacionado con los datos de Maps, el modelo de Gemini aprovecha Google Maps para proporcionar respuestas fácticas y actualizadas que sean 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 consultas geográficamente específicas.
  • Personalización mejorada: Adapta las recomendaciones y la información según las ubicaciones proporcionadas por el usuario.
  • Información contextual y widgets: Tokens de contexto para renderizar widgets interactivos de Google Maps junto con el contenido generado.

Comenzar

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

Python

# This will only work for SDK newer than 2.0.0
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

// This will only work for SDK newer than 2.0.0
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

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -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 de Google Geo mediante el uso de la API de Google Maps como fuente de fundamentación. Cuando la consulta 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 pertinentes para la ubicación proporcionada.

Por lo general, el proceso incluye lo siguiente:

  1. Consulta del usuario: Un usuario envía una consulta a tu aplicación, que puede incluir contexto geográfico (p.ej., "cafeterías cerca de mí" o "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 la latitude y la longitude del usuario. La herramienta es una herramienta de búsqueda textual y se comporta de manera similar a la búsqueda en Maps, ya que las consultas locales ("cerca de mí") usarán las coordenadas, mientras que es poco probable que las consultas 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 a Google Maps para obtener información pertinente (p.ej., lugares, opiniones, fotos, direcciones y horarios de atención).
  4. Generación fundamentada: Los datos de Maps recuperados se usan para informar la respuesta del modelo de Gemini, lo que garantiza la precisión y la pertinencia de los hechos.
  5. Respuesta y anotaciones: El modelo devuelve una respuesta de texto con anotaciones intercaladas que vinculan a las fuentes de Google Maps, lo que permite que los desarrolladores muestren citas y, de manera opcional, rendericen 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 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 de más de 250 millones de lugares en todo el mundo.

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

  • Proporcionar respuestas completas y precisas a preguntas específicas de la ubicación
  • Crear planificadores de viajes conversacionales y guías locales
  • Recomendar puntos de interés según la ubicación y las preferencias del usuario, como restaurantes o tiendas
  • Crear experiencias basadas en la ubicación para servicios sociales, de venta minorista o de 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 obtener indicaciones.

Casos de uso

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

Cómo controlar 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

# This will only work for SDK newer than 2.0.0
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

// This will only work for SDK newer than 2.0.0
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();

Cómo proporcionar personalización basada en la ubicación

Obtén recomendaciones adaptadas a las preferencias de un usuario y a un área geográfica específica.

Python

# This will only work for SDK newer than 2.0.0
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

// This will only work for SDK newer than 2.0.0
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();

Cómo ayudar con la planificación de itinerarios

Genera planes de varios días con indicaciones y datos sobre varias ubicaciones, ideales para aplicaciones de viajes.

Python

# This will only work for SDK newer than 2.0.0
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

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.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,
      enable_widget: true
    }]
  });
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -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 para la fundamentación con Google Maps.

Informa al usuario sobre el uso de fuentes de Google Maps

Con cada resultado fundamentado de Google Maps, recibirás anotaciones de origen en los bloques de contenido del paso model_output que admiten 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 de Google Maps asociadas y comunicar a los usuarios lo siguiente:

  • Las fuentes de Google Maps deben seguir inmediatamente el contenido generado que admiten las fuentes. Este contenido generado también se conoce como resultado fundamentado de Google Maps.
  • Las fuentes de Google Maps deben poder verse en una interacción del usuario.

Muestra las fuentes de Google Maps con vínculos de Google Maps

Para cada anotación de origen, se debe generar una vista previa del vínculo que cumpla con los siguientes requisitos:

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

Lineamientos de 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 y minúsculas de 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 términos 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 pertinentes y personalizadas, siempre incluye la latitude y la longitude en la configuración de la 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 los usuarios finales que se usan los datos de Google Maps para responder sus consultas, en especial cuando la herramienta está habilitada.
  • Desactiva la opción cuando no sea necesario: La fundamentación con Google Maps está desactivada de forma predeterminada. Solo habilítala ("tools": [{"type": "google_maps"}]) cuando una consulta 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 de Maps disponibles.
  • Alcance geográfico: La fundamentación con Google Maps está disponible a nivel global.
  • Estado predeterminado: La herramienta de fundamentación con Google Maps está desactivada de forma predeterminada. Debes habilitarla de forma explícita en tus solicitudes a la API.

Precios y límites de frecuencia

Los precios de la fundamentación con Google Maps se basan en las consultas. 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 cuenta 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 consultas a Google Maps desde una sola solicitud, se cuenta 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?