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 capacidades para lugares, clima y rutas. Puedes probar Maps Grounding Lite habilitándolo en cualquier herramienta que admita servidores de MCP.

Herramientas

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

  • Buscar lugares: Solicita información sobre lugares y obtén resúmenes de datos 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.

  • Compute routes: Solicita información sobre rutas a pie o en automóvil entre dos ubicaciones y devuelve información sobre la distancia y la duración de la ruta.

Habilitar el servidor de MCP de Maps Grounding Lite permite que los LLM llamen a las nuevas herramientas expuestas por 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 finalmente no incluya la información exacta que devolvió el servidor de MCP. Debes verificar la exactitud de la respuesta generada.

Probar la app de ejemplo de Maps Grounding Lite (abrir 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 realiza un seguimiento del uso de cada SKU de producto. En tu factura, se muestra un concepto 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 la India para obtener detalles sobre los precios.

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

Cuotas

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

  • Buscar lugares: 300 búsquedas por minuto y por proyecto
  • Buscar clima: 300 consultas por minuto y por proyecto
  • Compute routes: 300 consultas por minuto y por proyecto

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 la fuente.

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 pretendas usar con Maps Grounding Lite. No debes usar Maps Grounding Lite con ningún modelo que utilice los datos de entrada en el modelo para el entrenamiento o la mejora de modelos. Es tu responsabilidad asegurarte de que tu uso del modelo cumpla plenamente con las restricciones sobre el Contenido de Google Maps que se establecen 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 Grounding Lite de Maps incluye fuentes. Cuando presentes resultados que usen herramientas proporcionadas por Maps Grounding Lite, debes incluir las fuentes asociadas de Google Maps de una manera que cumpla con los siguientes requisitos:

  • Las fuentes de Google Maps deben aparecer inmediatamente después del contenido generado que admiten. Este contenido generado también se conoce como Salida fundamentada.
  • Las fuentes de Google Maps deben poder verse en una sola 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 los siguientes requisitos:

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 transmitible.

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

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

  1. En la consola de Google Cloud, elige el proyecto que deseas usar para Maps Grounding Lite.
  2. Habilita la facturación para el proyecto en la consola de Google Cloud.
  3. Habilita Maps Grounding Lite en la biblioteca de la API 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, haz lo siguiente:

  1. Crea o configura una clave de API siguiendo los pasos que se indican en Cómo comenzar a usar Google Maps Platform.
  2. 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 MCP del LLM.

Autentica con OAuth

Puedes autenticarte con OAuth creando credenciales de OAuth y pasándolas al host de MCP o a la aplicación del servidor de MCP.

Para autenticarte con OAuth, haz lo siguiente:

  1. En la consola de Google Cloud, elige el proyecto que deseas usar para Maps Grounding Lite.
  2. En el menú APIs y servicios, selecciona Credenciales.
  3. En el menú superior, selecciona Crear credenciales > ID de cliente de OAuth.
  4. Si el proyecto no tiene una pantalla de consentimiento configurada, haz clic en Configurar pantalla de consentimiento y sigue las instrucciones en pantalla.
  5. En la sección Métricas, haz clic en Crear cliente de OAuth.
  6. 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.
  7. Especifica los detalles adicionales que son relevantes para tu tipo de solicitud. Por ejemplo, si creas una aplicación web, agrega URIs autorizados para las solicitudes del navegador y del servidor.
  8. Una vez que se cree tu cliente, guarda el ID y el secreto del cliente.
  9. Cuando configures tu host o aplicación del servidor de MCP para acceder a Maps Grounding Lite, pasa tu ID de cliente y secreto de OAuth. También debes solicitar el siguiente alcance: 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. Para ello, sigue la documentación de configuración de MCP correspondiente y usa la URL del servidor de MCP de Maps Grounding Lite: https://mapstools.googleapis.com/mcp.

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

Configura Grounding Lite de Maps 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.

  1. Una vez que instales la CLI de Gemini, podrás 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 la configuración del usuario.

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

    > /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

  3. Comienza a hacer preguntas relacionadas con Maps con la CLI. Por ejemplo, prueba con "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 MCP de Grounding Lite con el Kit de desarrollo de agentes (ADK) y Python, Java o TypeScript.

Python

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 y realiza interacciones
  1. Set Environment Variable:
    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"
  2. Ejecuta adk web:
    Ejecuta el siguiente comando para iniciar la interfaz web del ADK: 
    adk web
  3. Interactúa en la IU:
    • Selecciona la travel_planner_agent.
    • Prueba instrucciones como las siguientes:
      • "Estaré en San Francisco mañana. ¿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 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 tus comentarios sobre Maps Grounding Lite, usa los siguientes formularios: