Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Maps Grounding Lite

Google Maps Platform Grounding Lite es un servicio compatible con el Protocolo de contexto del modelo (MCP) que facilita la fundamentación de tus aplicaciones de IA con datos geoespaciales confiables de Google Maps. El servidor de MCP proporciona herramientas que permiten que los LLM accedan a funciones para lugares, clima y rutas, y que resuelvan nombres de ubicaciones y URLs de Google Maps en IDs de lugar. Para probar Maps Grounding Lite, habilítalo en cualquier herramienta que admita servidores de MCP.

Herramientas

Maps Grounding Lite proporciona herramientas que permiten que los LLM accedan a las siguientes funciones de Google Maps:

Buscar lugares: Solicita información sobre lugares y obtén resúmenes de datos de lugares generados por IA, así como IDs de lugar, coordenadas de latitud y longitud, y vínculos de Google Maps para cada uno de los lugares incluidos en el resumen. Puedes usar los IDs de lugar y las coordenadas de latitud y longitud que se devuelven con otras APIs de Google Maps Platform para mostrar lugares en un mapa.
Buscar el clima: Solicita información sobre el clima y devuelve las condiciones actuales, los pronósticos por hora y los pronósticos diarios.
Calcular rutas: Solicita información sobre rutas en automóvil o a pie entre dos ubicaciones y devuelve información sobre la distancia y la duración de la ruta.

Nota: Maps Grounding Lite no proporciona información de rutas paso a paso, instrucciones sobre cómo llegar, tráfico en tiempo real ni navegación.
Resolve names y Resolve Maps URLs: Resuelve nombres de ubicaciones, direcciones y URLs de Google Maps en IDs de lugar. Para obtener más información, consulta la API de Resolution.

Habilitar el servidor de MCP de Maps Grounding Lite permite que los LLM llamen a las nuevas herramientas que expone el servidor para devolver información de fundamentación adicional para los tipos de datos mencionados anteriormente. Si bien el LLM puede usar esta información adicional para el contexto, es posible que la respuesta que genere el LLM no incluya la información exacta que devuelve el servidor de MCP. Debes verificar la exactitud de la respuesta generada.

API de Resolution

Maps Grounding Lite proporciona la API de Resolution, que te permite resolver texto de ubicación de formato libre y URLs en identificadores de lugares estructurados de Google Maps. La API de Resolution está disponible como métodos de REST y como herramientas en el servidor de MCP de Maps Grounding Lite:

Resolver nombres (REST, MCP): Resuelve un lote de nombres o direcciones de ubicaciones en entidades de lugares específicos en Google Maps. Esto es útil para fundamentar las consultas no estructuradas de los usuarios en IDs de lugar estables.
Resuelve URLs de Maps (REST, MCP): Resuelve un lote de URLs de Google Maps en entidades de lugares específicos. Los formatos admitidos incluyen URLs de lugares estándar y URLs abreviadas.

Puedes usar los IDs de lugar que se devuelven con otras APIs de Google Maps Platform. Cada respuesta también incluye un vínculo que guarda los lugares resueltos como una lista en Google Maps.

Para obtener más información, consulta la API de Maps Tools Resolution.

Prueba la app de ejemplo de Maps Grounding Lite (se abre en una pestaña nueva)

Facturación y cuotas

Cómo se te factura

Con el modelo de precios de pago por uso de Google Maps Platform, el uso de Maps Grounding Lite se calcula para cada solicitud, en la que cada solicitud representa un evento de facturación. Se hace un seguimiento del uso de cada SKU de producto. En tu factura, se muestra una línea de pedido para cada SKU, además de los cargos totales. Consulta la descripción general de los informes para obtener más información.

Consulta la tabla de precios principal y la tabla de precios de India para obtener detalles sobre los precios.

Las solicitudes a la API de Resolution (ResolveNames y ResolveMapsUrls) se facturan sin cargo con el SKU API de Places Text Search Essentials (IDs Only).

Maps Grounding Lite también se ofrece a través de los paquetes Essentials y Pro. Suscríbete para ahorrar

Cuotas

Las siguientes cuotas se aplican a las herramientas y APIs que proporciona Maps Grounding Lite:

Búsqueda de lugares: 300 consultas por minuto, por proyecto
Búsqueda del clima: 300 consultas por minuto por proyecto
Compute routes: 300 consultas por minuto por proyecto
Resolver nombres: 600 consultas por minuto por proyecto
Resolver URLs de Maps: 600 búsquedas por minuto por proyecto

Cada solicitud a la API de Resolution cuenta como una consulta, independientemente de la cantidad de elementos que contenga.

Políticas y Condiciones del Servicio

Maps Grounding Lite está sujeto a las Condiciones del Servicio de Google Maps Platform, incluidas las condiciones específicas del servicio para este servicio. En esta sección, se describen los requisitos adicionales de uso del servicio para Maps Grounding Lite, incluidos los LLM compatibles y los requisitos de atribución de fuentes.

Requisitos para los LLM compatibles

Solo puedes usar Maps Grounding Lite con un LLM que cumpla con las Condiciones del Servicio de Google Maps Platform.

Por ejemplo, eres responsable de garantizar que el contenido de Google Maps no se almacene en caché, no se almacene ni se use para mejorar el LLM que elijas usar. Antes de usar Maps Grounding Lite, deberás revisar las Condiciones del Servicio de cualquier modelo que quieras usar con Maps Grounding Lite. No debes usar Maps Grounding Lite con ningún modelo que use los datos ingresados en el modelo para ningún entrenamiento o mejora del modelo. Eres responsable de garantizar que tu uso del modelo cumpla por completo con las restricciones del contenido de Google Maps que se indican en las Condiciones del Servicio de Google Maps Platform, incluidas las condiciones específicas del servicio.

Requisitos de atribución para las fuentes de Google Maps

Cada respuesta de la herramienta de Maps Grounding Lite incluye fuentes. Cuando presentes resultados que usen herramientas proporcionadas por Maps Grounding Lite, debes incluir las fuentes de Google Maps asociadas de una manera que cumpla con los siguientes requisitos:

Las fuentes de Google Maps deben seguir inmediatamente al contenido generado que respaldan. Este contenido generado también se conoce como Resultado fundamentado.
Las fuentes de Google Maps deben poder verse en una interacción del usuario.

Fuentes de la herramienta Buscar lugares

El campo places de la herramienta search_places proporciona fuentes que respaldan la summary. Para places, se devuelven los siguientes metadatos:

place (nombre del recurso)
id
location
googleMapsLinks

Para cada lugar, debes generar una vista previa del vínculo que cumpla con estos requisitos:

Atribuye cada fuente a Google Maps, según los lineamientos de atribución de texto de Maps Grounding Lite.
Vincula a la fuente con el places.googleMapsLinks.placeUrl de la respuesta.

Configura los LLM para que usen el servidor de MCP

Para usar Maps Grounding Lite, primero necesitas un proyecto de Google Cloud con el servicio de la API de Maps Grounding Lite habilitado, así como una clave de API o un ID de cliente de OAuth. Luego, puedes configurar los LLM para que accedan al servidor de MCP. El servidor de MCP de Grounding Lite usa el transporte HTTP transmisible.

Habilita el servicio Maps Grounding Lite en tu proyecto de Google Cloud.

Para habilitar la API en tu proyecto, sigue estos pasos:

En la consola de Google Cloud, elige el proyecto que quieras usar para Maps Grounding Lite.
Habilita la facturación para el proyecto en la consola de Google Cloud.
Habilita Maps Grounding Lite en la biblioteca de APIs de la consola de Google Cloud.

Autentica con una clave de API

Puedes usar una clave de API existente con Maps Grounding Lite o crear una nueva, siempre y cuando habilites el servicio de la API de Maps Grounding Lite tanto en el proyecto de Google Cloud como en la clave.

Para autenticarte con una clave de API, sigue estos pasos:

Sigue los pasos que se indican en Comienza a usar Google Maps Platform para crear o configurar una clave de API.
Pasa la clave al servidor de MCP con el encabezado X-Goog-Api-Key. Debes especificarlo como un encabezado HTTP personalizado en la configuración de la herramienta de MCP del LLM.

Autentica con OAuth

Para autenticarte con OAuth, crea credenciales de OAuth y pásalas a la aplicación host o de servidor de MCP.

Para autenticarte con OAuth, sigue estos pasos:

En la consola de Google Cloud, elige el proyecto que quieras usar para Maps Grounding Lite.
En el menú APIs y servicios, selecciona Credenciales.
En el menú superior, selecciona Crear credenciales > ID de cliente de OAuth.
Si el proyecto no tiene una pantalla de consentimiento configurada, haz clic en Configurar pantalla de consentimiento y sigue las instrucciones en pantalla.
En la sección Métricas, haz clic en Crear cliente de OAuth.
En la pantalla Crear ID de cliente de OAuth, selecciona un tipo de aplicación y, luego, ingresa un nombre para el ID de cliente.
Especifica los detalles adicionales que sean pertinentes para tu tipo de solicitud. Por ejemplo, si creas una aplicación web, agrega URIs autorizados para las solicitudes del navegador y del servidor.
Una vez que se cree el cliente, guarda el ID de cliente y el secreto.
Cuando configures tu aplicación de host o servidor de MCP para acceder a Maps Grounding Lite, pasa tu ID y secreto de cliente de OAuth. También debes solicitar el siguiente permiso: https://www.googleapis.com/auth/maps-platform.mapstools.

Para obtener más información, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Configura los LLM para que accedan al servidor de MCP de Maps Grounding Lite

Una vez que tengas un proyecto de Google Cloud con el servicio de la API de Maps Grounding Lite habilitado y credenciales válidas, como una clave de API o un ID y un secreto de cliente de OAuth, puedes configurar los LLM para que accedan al servidor de MCP siguiendo la documentación de configuración de MCP correspondiente y usando la URL del servidor de MCP de Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Para obtener más información, consulta Configura MCP en una aplicación de IA.

Configura Maps Grounding Lite con Gemini CLI

En esta sección, se proporciona un ejemplo de cómo configurar el servidor de MCP de Maps Grounding Lite con la CLI de Gemini. Para obtener más detalles, consulta Servidores de MCP con la CLI de Gemini.

Una vez que instales Gemini CLI, puedes usar el comando add para configurar el servidor de MCP de Maps Grounding Lite:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
Si la configuración se realizó correctamente, deberías ver una confirmación de que el servidor se agregó a tu configuración de usuario.

Para validar que el servidor funcione correctamente, ejecuta el comando /mcp list:

> /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

Comienza a hacer preguntas relacionadas con Maps con la CLI. Por ejemplo, prueba "Recomiéndame algunos restaurantes en Mountain View", que debería llamar a la herramienta search_places en tu nombre.

Configura Grounding Lite con el Kit de desarrollo de agentes (ADK)

En esta sección, se proporcionan ejemplos que muestran cómo configurar el servidor de MCP de Grounding Lite con el Kit de desarrollo de agentes (ADK) y Python, Java o TypeScript.

Python

Puedes encontrar una implementación completa de este ejemplo en GitHub, en el repositorio adk-samples.

Paso 1: Define tu agente con `McpToolset` para Google Maps Grounding Lite

Modifica tu archivo agent.py. Reemplaza YOUR_GOOGLE_MAPS_API_KEY por tu clave de API real.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)

Paso 2: Asegúrate de que exista `init.py`

Asegúrate de tener un __init__.py en el mismo directorio que tu agent.py:

from . import agent

Paso 3: Ejecuta `adk web` e interactúa

Establece la variable de entorno:
Establece tu clave de API de Google Maps como una variable de entorno en tu terminal:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Ejecuta adk web:
Ejecuta el siguiente comando para iniciar la interfaz web del ADK:
```
adk web
        
```
Interactúa en la IU:
- Selecciona la travel_planner_agent.
- Prueba instrucciones como las siguientes:
  - "Mañana estaré en San Francisco. ¿Cómo está el clima?"
  - "Encuentra cafeterías cerca del parque Golden Gate".
  - "Obtén instrucciones sobre cómo llegar desde Googleplex hasta SFO".

Java

Define un agente que inicialice el McpToolset en Java. Reemplaza YOUR_GOOGLE_MAPS_API_KEY_HERE por la clave de API real que obtuviste si no usas una variable de entorno.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

Define un agente que inicialice el MCPToolset en TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

Comparte tus comentarios

Para compartir comentarios sobre Maps Grounding Lite, usa los siguientes formularios: