Maps Grounding Lite

Google Maps Platform Grounding Lite ist ein Dienst mit Unterstützung für das Model Context Protocol (MCP), mit dem Sie Ihre KI-Anwendungen ganz einfach mit vertrauenswürdigen Geodaten aus Google Maps fundieren können. Der MCP-Server bietet Tools, mit denen LLMs auf Funktionen für Orte, Wetter und Routen zugreifen und Ortsnamen und Google Maps-URLs in Orts-IDs auflösen können. Sie können Maps Grounding Lite ausprobieren, indem Sie es in einem Tool aktivieren, das MCP-Server unterstützt.

Tools

Maps Grounding Lite bietet Tools, mit denen LLMs auf die folgenden Google Maps-Funktionen zugreifen können:

• Orte suchen: Informationen zu Orten anfordern und KI-generierte Zusammenfassungen von Ortsdaten sowie Orts-IDs, Breiten- und Längengradkoordinaten und Google Maps-URLs für jeden in der Zusammenfassung enthaltenen Ort abrufen. Sie können die zurückgegebenen Orts-IDs und die Koordinaten für den Längen- und Breitengrad mit anderen Google Maps Platform APIs verwenden, um Orte auf einer Karte anzuzeigen.
• Wetter abfragen: Informationen zum Wetter anfordern und aktuelle Bedingungen, stündliche Vorhersagen und tägliche Vorhersagen zurückgeben.

• Routen berechnen: Informationen zu Fahr- oder Fußgängerrouten zwischen zwei Orten anfordern und Informationen zur Routenlänge und ‑dauer zurückgeben.

• Namen auflösen und Maps-URLs auflösen: Ortsnamen, Adressen und Google Maps-URLs in Orts-IDs auflösen. Weitere Informationen finden Sie unter Resolution API.

Wenn der Maps Grounding Lite-MCP-Server aktiviert ist, können LLMs die neuen Tools aufrufen, die vom Server bereitgestellt werden, um zusätzliche Fundierungsinformationen für die oben aufgeführten Datentypen zurückzugeben. Das LLM kann diese zusätzlichen Informationen zwar als Kontext verwenden, die vom LLM letztendlich generierte Antwort enthält jedoch möglicherweise nicht die genauen Informationen, die vom MCP-Server zurückgegeben wurden. Sie sollten die Richtigkeit der generierten Antwort überprüfen.

Resolution API

Maps Grounding Lite bietet die Resolution API, mit der Sie Ortsangaben in freiem Text und URLs in strukturierte Google Maps-Ortskennungen auflösen können. Die Resolution API ist als REST-Methoden und als Tools auf dem Maps Grounding Lite-MCP-Server verfügbar:

• Namen auflösen (REST, MCP): Eine Gruppe von Ortsnamen oder Adressen in bestimmte Ortselemente auf Google Maps auflösen. Das ist nützlich, um unstrukturierte Nutzeranfragen in stabilen Orts-IDs zu fundieren.
• Maps-URLs auflösen (REST, MCP): Eine Gruppe von Google Maps-URLs in bestimmte Ortsentitäten auflösen. Zu den unterstützten Formaten gehören Standard-Orts-URLs und gekürzte URLs.

Sie können die zurückgegebenen Orts-IDs mit anderen Google Maps Platform APIs verwenden. Jede Antwort enthält außerdem einen Link, über den die aufgelösten Orte als Liste in Google Maps gespeichert werden können.

Weitere Informationen finden Sie unter Maps Tools Resolution API.

Beispiel-App „Maps Grounding Lite“ ausprobieren (wird in einem neuen Tab geöffnet)

Abrechnung und Kontingente

Abrechnung

Beim „Pay as you go“-Preismodell der Google Maps Platform wird die Nutzung von Maps Grounding Lite pro Anfrage berechnet. Jede Anfrage entspricht einem Abrechnungsereignis. Die Nutzung wird jeweils pro Produkt-SKU erfasst. Ihre Rechnung enthält neben den Gesamtkosten eine Position für jede SKU. Weitere Informationen finden Sie in der Berichtsübersicht.

Weitere Informationen zu den Preisen finden Sie in der Hauptpreistabelle und der Preistabelle für Indien.

Anfragen an die Resolution API (ResolveNames und ResolveMapsUrls) werden kostenlos über die SKU Places API Text Search Essentials (IDs Only) abgerechnet.

Maps Grounding Lite wird auch über die Essentials- und Pro-Pakete Abo abschließen und sparen angeboten.

Kontingente

Für die von Maps Grounding Lite bereitgestellten Tools und APIs gelten die folgenden Kontingente:

• Orte suchen: 300 Anfragen pro Minute und Projekt.
• Wetter abfragen: 300 Anfragen pro Minute und Projekt.
• Routen berechnen: 300 Anfragen pro Minute und Projekt.
• Namen auflösen: 600 Abfragen pro Minute und Projekt.
• Maps-URLs auflösen: 600 Anfragen pro Minute und Projekt.

Jede Resolution API-Anfrage zählt als eine Abfrage, unabhängig davon, wie viele Elemente sie enthält.

Richtlinien und Nutzungsbedingungen

Maps Grounding Lite unterliegt den Nutzungsbedingungen für die Google Maps Platform, einschließlich der dienstspezifischen Nutzungsbedingungen für diesen Dienst. In diesem Abschnitt werden zusätzliche Anforderungen für die Nutzung des Dienstes für Maps Grounding Lite beschrieben, einschließlich kompatibler LLMs und Anforderungen an die Quellenangabe.

Anforderungen an kompatible LLMs

Sie dürfen Maps Grounding Lite nur mit einem LLM verwenden, das den Nutzungsbedingungen der Google Maps Platform entspricht.

Sie sind beispielsweise dafür verantwortlich, dass Google Maps-Inhalte nicht von dem von Ihnen verwendeten LLM im Cache gespeichert, gespeichert oder zur Verbesserung des LLM verwendet werden. Bevor Sie Maps Grounding Lite verwenden, müssen Sie die Nutzungsbedingungen für alle Modelle lesen, die Sie mit Maps Grounding Lite verwenden möchten. Sie dürfen Maps Grounding Lite nicht mit Modellen verwenden, die die in das Modell eingegebenen Daten für das Modelltraining oder die Modellverbesserung verwenden. Sie sind dafür verantwortlich, dass Ihre Nutzung des Modells vollständig den Einschränkungen für Google Maps-Inhalte in den Nutzungsbedingungen der Google Maps Platform, einschließlich der dienstspezifischen Nutzungsbedingungen, entspricht.

Anforderungen bezüglich Quellenangaben für Google Maps-Quellen

Jede Toolantwort von Maps Grounding Lite enthält Quellen. Wenn Sie Ergebnisse präsentieren, die Tools von Maps Grounding Lite verwenden, müssen Sie die zugehörigen Google Maps-Quellen so angeben, dass die folgenden Anforderungen erfüllt sind:

• Die Google Maps-Quellen müssen unmittelbar auf die generierten Inhalte folgen, die sie unterstützen. Diese generierten Inhalte werden auch als fundierte Ausgabe bezeichnet.
• Die Google Maps-Quellen müssen innerhalb einer Nutzerinteraktion sichtbar sein.

Quellen für das Tool „Orte suchen“

Das Feld places des search_places-Tools enthält Quellen, die die summary unterstützen. Für places werden die folgenden Metadaten zurückgegeben:

• place (Ressourcenname)
• id
• location
• googleMapsLinks

Für jeden Ort müssen Sie eine Linkvorschau generieren, die die folgenden Anforderungen erfüllt:

• Geben Sie jede Quelle gemäß den Richtlinien für die Textquellenangabe für Maps Grounding Lite als Google Maps an.
• Verknüpfen Sie die Quelle mit der places.googleMapsLinks.placeUrl aus der Antwort.

LLMs für die Verwendung des MCP-Servers konfigurieren

Wenn Sie Maps Grounding Lite verwenden möchten, benötigen Sie zuerst ein Google Cloud-Projekt, in dem der API-Dienst Maps Grounding Lite aktiviert ist, sowie entweder einen API-Schlüssel oder eine OAuth-Client-ID. Anschließend können Sie LLMs für den Zugriff auf den MCP-Server konfigurieren. Der Grounding Lite-MCP-Server verwendet den streamfähigen HTTP-Transport.

Aktivieren Sie den Dienst Maps Grounding Lite in Ihrem Google Cloud-Projekt.

So aktivieren Sie die API in Ihrem Projekt:

1. Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für Maps Grounding Lite verwenden möchten.
2. Aktivieren Sie die Abrechnung für das Projekt in der Google Cloud Console.
3. Aktivieren Sie Maps Grounding Lite in der Google Cloud Console API-Bibliothek.

Mit einem API-Schlüssel authentifizieren

Sie können einen vorhandenen API-Schlüssel mit Maps Grounding Lite verwenden oder einen neuen erstellen, solange Sie den API-Dienst Maps Grounding Lite sowohl für das Google Cloud-Projekt als auch für den Schlüssel aktivieren.

So authentifizieren Sie sich mit einem API-Schlüssel:

1. Erstellen oder konfigurieren Sie einen API-Schlüssel, indem Sie die Schritte unter Erste Schritte mit der Google Maps Platform ausführen.
2. Übergeben Sie den Schlüssel mit dem Header X-Goog-Api-Key an den MCP-Server. Sie müssen dies als benutzerdefinierten HTTP-Header in der MCP-Toolkonfiguration des LLM angeben.

Mit OAuth authentifizieren

Sie können sich mit OAuth authentifizieren, indem Sie OAuth-Anmeldedaten erstellen und an die MCP-Host- oder MCP-Serveranwendung übergeben.

So authentifizieren Sie sich mit OAuth:

1. Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für Maps Grounding Lite verwenden möchten.
2. Wählen Sie im Menü APIs und Dienste die Option Anmeldedaten aus.
3. Wählen Sie im Menü oben Anmeldedaten erstellen > OAuth-Client-ID aus.
4. Wenn für das Projekt kein Zustimmungsbildschirm konfiguriert ist, klicken Sie auf Zustimmungsbildschirm konfigurieren und folgen Sie der Anleitung auf dem Bildschirm.
5. Klicken Sie im Bereich Messwerte auf OAuth-Client erstellen.
6. Wählen Sie auf dem Bildschirm OAuth-Client-ID erstellen einen Anwendungstyp aus und geben Sie einen Namen für die Client-ID ein.
7. Geben Sie die zusätzlichen Details an, die für Ihren Anwendungstyp relevant sind. Wenn Sie beispielsweise eine Webanwendung erstellen, fügen Sie autorisierte URIs für Browser- und Serveranfragen hinzu.
8. Speichern Sie die Client-ID und den Clientschlüssel, nachdem der Client erstellt wurde.
9. Wenn Sie Ihre MCP-Host- oder MCP-Serveranwendung für den Zugriff auf Maps Grounding Lite konfigurieren, übergeben Sie Ihre OAuth-Client-ID und Ihr OAuth-Secret. Außerdem müssen Sie den folgenden Bereich anfordern: https://www.googleapis.com/auth/maps-platform.mapstools.

Weitere Informationen finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

LLMs für den Zugriff auf den Maps Grounding Lite-MCP-Server konfigurieren

Sobald Sie ein Google Cloud-Projekt mit aktiviertem Maps Grounding Lite API-Dienst und gültigen Anmeldedaten wie einem API-Schlüssel oder einer OAuth-Client-ID und einem Secret haben, können Sie LLMs für den Zugriff auf den MCP-Server konfigurieren. Folgen Sie dazu der entsprechenden MCP-Konfigurationsdokumentation und verwenden Sie die MCP-Server-URL für Maps Grounding Lite: https://mapstools.googleapis.com/mcp.

Weitere Informationen finden Sie unter MCP in einer KI-Anwendung konfigurieren.

Maps Grounding Lite mit der Gemini CLI konfigurieren

In diesem Abschnitt wird anhand eines Beispiels gezeigt, wie Sie den Maps Grounding Lite-MCP-Server mit der Gemini CLI konfigurieren. Weitere Informationen finden Sie unter MCP-Server mit der Gemini CLI.

1. Nachdem Sie die Gemini CLI installiert haben, können Sie den MCP-Server für Maps Grounding Lite mit dem Befehl „add“ konfigurieren:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
   

   Wenn die Konfiguration erfolgreich war, sollten Sie eine Bestätigung sehen, dass der Server Ihren Nutzereinstellungen hinzugefügt wurde.

2. Führen Sie den Befehl /mcp list aus, um zu prüfen, ob der Server ordnungsgemäß funktioniert:

   > /mcp list
   
   Configured MCP servers:
   
   maps-grounding-lite-mcp - Ready (5 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_places
   

3. Stellen Sie über die Befehlszeile Fragen zu Google Maps. Versuchen Sie es beispielsweise mit „Empfehle mir einige Restaurants in Mountain View“. Dadurch sollte das Tool „search_places“ in Ihrem Namen aufgerufen werden.

Fundierung Lite mit dem Agent Development Kit (ADK) konfigurieren

In diesem Abschnitt finden Sie Beispiele, die zeigen, wie Sie den Grounding Lite-MCP-Server mit dem Agent Development Kit (ADK) und entweder Python, Java oder TypeScript konfigurieren.

# ./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"
                }
            )
        )
    ]
)
    

from . import agent
    

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();
        }
    }
}
    

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"
            }
        })
    ],
});
    

Feedback geben

Wenn Sie Feedback zu Maps Grounding Lite geben möchten, verwenden Sie die folgenden Formulare:

• Fehler melden
• Feature Request senden
• Feedback geben