Maps Grounding Lite

Google Maps Platform Grounding Lite to usługa z obsługą protokołu Model Context Protocol (MCP), która ułatwia grounding aplikacji opartych na AI za pomocą zaufanych danych geoprzestrzennych z Map Google. Serwer MCP udostępnia narzędzia, które umożliwiają LLM dostęp do funkcji związanych z miejscami, pogodą i trasami oraz rozpoznawanie nazw lokalizacji i adresów URL Map Google jako identyfikatorów miejsc. Możesz wypróbować Maps Grounding Lite, włączając tę funkcję w dowolnym narzędziu obsługującym serwery MCP.

Narzędzia

Maps Grounding Lite udostępnia narzędzia, które umożliwiają LLM dostęp do tych funkcji Map Google:

  • Wyszukiwanie miejsc: poproś o informacje o miejscach i uzyskaj wygenerowane przez AI podsumowania danych o miejscach, a także identyfikatory miejsc, współrzędne szerokości i długości geograficznej oraz linki do Map Google dla każdego miejsca uwzględnionego w podsumowaniu. Zwrócone identyfikatory miejsc oraz współrzędne szerokości i długości geograficznej możesz używać z innymi interfejsami API Google Maps Platform, aby wyświetlać miejsca na mapie.
  • Sprawdzanie pogody: poproś o informacje o pogodzie i uzyskaj aktualne warunki, prognozy godzinowe i prognozy dzienne.

  • Obliczanie tras: poproś o informacje o trasach dojazdu lub trasach pieszych między 2 lokalizacjami i uzyskaj informacje o odległości i czasie trwania trasy.

  • Rozpoznawanie nazw i Rozpoznawanie adresów URL w Mapach: rozpoznawanie nazw lokalizacji, adresów i adresów URL Map Google na potrzeby identyfikatorów miejsc. Więcej informacji znajdziesz w artykule na temat interfejsu Resolution API.

Włączenie serwera MCP Maps Grounding Lite umożliwia LLM wywoływanie nowych narzędzi udostępnianych przez serwer w celu zwracania dodatkowych informacji o ugruntowaniu dla wymienionych wyżej typów danych. LLM może wykorzystać te dodatkowe informacje jako kontekst, ale odpowiedź, którą ostatecznie wygeneruje, może nie zawierać dokładnych informacji zwróconych przez serwer MCP. Sprawdź, czy wygenerowana odpowiedź jest prawidłowa.

Resolution API

Maps Grounding Lite udostępnia interfejs Resolution API, który umożliwia przekształcanie tekstu lokalizacji w formacie swobodnym i adresów URL w uporządkowane identyfikatory miejsc w Mapach Google. Interfejs Resolution API jest dostępny jako metody REST i narzędzia na serwerze Maps Grounding Lite MCP:

  • Rozpoznawanie nazw (REST, MCP): rozpoznawanie zbioru nazw lub adresów lokalizacji i przypisywanie ich do konkretnych miejsc w Mapach Google. Jest to przydatne do przekształcania nieustrukturyzowanych zapytań użytkowników w stabilne identyfikatory miejsc.
  • Resolve Maps URLs (REST, MCP): rozpoznawanie zbioru adresów URL Map Google jako konkretnych elementów miejsc. Obsługiwane formaty obejmują standardowe adresy URL miejsc i skrócone adresy URL.

Zwróconych identyfikatorów miejsc możesz używać z innymi interfejsami API Google Maps Platform. Każda odpowiedź zawiera też link, który zapisuje znalezione miejsca jako listę w Mapach Google.

Więcej informacji znajdziesz w artykule Maps Tools Resolution API.

Wypróbuj przykładową aplikację Maps Grounding Lite (otwiera się w nowej karcie)

Rozliczenia i limity

Jak naliczane są opłaty

W modelu płatności według wykorzystania Google Maps Platform wykorzystanie Maps Grounding Lite jest obliczane dla każdego żądania, przy czym każde żądanie reprezentuje jedno zdarzenie rozliczeniowe. Wykorzystanie jest śledzone dla każdego kodu SKU usługi. Na rachunku oprócz łącznych opłat widoczny jest element zamówienia dla każdego kodu SKU. Więcej informacji znajdziesz w omówieniu raportowania.

Szczegółowe informacje o cenach znajdziesz w głównej tabeli cen i tabeli cen w Indiach.

Żądania do interfejsu Resolution API (ResolveNames i ResolveMapsUrls) są rozliczane bezpłatnie w ramach kodu SKU Places API Wyszukaj tekst Essentials (tylko identyfikatory).

Usługa Maps Grounding Lite jest też dostępna w ramach pakietów Essentials i Pro Subscribe to save.

Limity

W przypadku narzędzi i interfejsów API udostępnianych przez Maps Grounding Lite obowiązują te limity:

  • Wyszukiwanie miejsc: 300 zapytań na minutę na projekt.
  • Wyszukiwanie informacji o pogodzie: 300 zapytań na minutę na projekt.
  • Obliczanie tras: 300 zapytań na minutę na projekt.
  • Rozpoznawanie nazw: 600 zapytań na minutę na projekt.
  • Resolve Maps URLs: 600 zapytań na minutę na projekt.

Każde żądanie do interfejsu Resolution API liczy się jako jedno zapytanie, niezależnie od tego, ile elementów zawiera.

Zasady i warunki korzystania z usługi

Usługa Maps Grounding Lite podlega Warunkom korzystania z Google Maps Platform, w tym szczegółowym warunkom korzystania z tej usługi. W tej sekcji opisano dodatkowe wymagania dotyczące korzystania z usługi Maps Grounding Lite, w tym zgodne modele LLM i wymagania dotyczące podawania źródła.

Wymagania dotyczące zgodnych modeli LLM

Z usługi Maps Grounding Lite możesz korzystać tylko z modelem LLM, który jest zgodny z Warunkami korzystania z usługi Google Maps Platform.

Na przykład musisz zadbać o to, aby treści Map Google nie były przechowywane w pamięci podręcznej ani w inny sposób, a także aby nie były używane do ulepszania wybranego przez Ciebie modelu LLM. Zanim zaczniesz korzystać z Grounding Lite w Mapach, musisz zapoznać się z Warunkami korzystania z usługi w przypadku każdego modelu, którego chcesz używać z Grounding Lite w Mapach. Nie wolno używać usługi Maps Grounding Lite z żadnymi modelami, które wykorzystują dane wejściowe do trenowania lub ulepszania modelu. Ponosisz odpowiedzialność za zapewnienie, że korzystanie z modelu jest w pełni zgodne z ograniczeniami dotyczącymi treści Map Google określonymi w Warunkach korzystania z usługi Google Maps Platform, w tym w warunkach korzystania z konkretnych usług.

Wymagania dotyczące podawania źródeł w przypadku Map Google

Każda odpowiedź narzędzia z Grounding Lite w Mapach zawiera źródła. Podczas prezentowania wyników, które korzystają z narzędzi udostępnianych przez Maps Grounding Lite, musisz uwzględnić powiązane źródła Map Google w sposób spełniający te wymagania:

  • Źródła Map Google muszą znajdować się bezpośrednio po wygenerowanych treściach, które te źródła obsługują. Te wygenerowane treści są też nazywane uzasadnionymi danymi wyjściowymi.
  • Źródła Map Google muszą być widoczne w ramach jednej interakcji użytkownika.

Źródła narzędzia do wyszukiwania miejsc

Pole search_places narzędzia places zawiera źródła, które potwierdzają summary. W przypadku places zwracane są te metadane:

  • place (nazwa zasobu)
  • id
  • location
  • googleMapsLinks

W przypadku każdego miejsca musisz wygenerować podgląd linku, który spełnia te wymagania:

Konfigurowanie LLM pod kątem korzystania z serwera MCP

Aby korzystać z Maps Grounding Lite, musisz najpierw mieć projekt Google Cloud z włączoną usługą interfejsu API Maps Grounding Lite oraz klucz interfejsu API lub identyfikator klienta OAuth. Następnie możesz skonfigurować LLM, aby miały dostęp do serwera MCP. Serwer Grounding Lite MCP używa transportu HTTP z możliwością strumieniowania.

Włącz usługę Maps Grounding Lite w projekcie Google Cloud.

Aby włączyć interfejs API w projekcie:

  1. W konsoli Google Cloud wybierz projekt, którego chcesz używać w przypadku Maps Grounding Lite.
  2. Włącz rozliczenia za projekt w konsoli Google Cloud.
  3. Włącz Maps Grounding Lite w bibliotece interfejsów API konsoli Google Cloud.

Uwierzytelnianie za pomocą klucza interfejsu API

Możesz użyć istniejącego klucza interfejsu API z Maps Grounding Lite lub utworzyć nowy, o ile włączysz usługę Maps Grounding Lite API zarówno w projekcie w chmurze Google Cloud, jak i w kluczu.

Aby uwierzytelnić się za pomocą klucza interfejsu API:

  1. Utwórz lub skonfiguruj klucz interfejsu API, wykonując czynności opisane w artykule Pierwsze kroki z Google Maps Platform.
  2. Przekaż klucz do serwera MCP za pomocą nagłówka X-Goog-Api-Key. Musisz określić ten nagłówek jako niestandardowy nagłówek HTTP w konfiguracji narzędzia MCP LLM.

Uwierzytelnianie za pomocą OAuth

Możesz uwierzytelniać się za pomocą protokołu OAuth, tworząc dane uwierzytelniające OAuth i przekazując je do hosta MCP lub aplikacji serwera MCP.

Aby uwierzytelnić za pomocą protokołu OAuth:

  1. W konsoli Google Cloud wybierz projekt, którego chcesz używać w przypadku Maps Grounding Lite.
  2. W menu Interfejsy API i usługi wybierz Dane logowania.
  3. W górnym menu wybierz Utwórz dane logowania > Identyfikator klienta OAuth.
  4. Jeśli projekt nie ma skonfigurowanego ekranu zgody, kliknij Skonfiguruj ekran zgody i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.
  5. W sekcji Dane kliknij Utwórz klienta OAuth.
  6. Na ekranie Utwórz identyfikator klienta OAuth wybierz typ aplikacji i wpisz nazwę identyfikatora klienta.
  7. Podaj dodatkowe informacje, które są istotne dla Twojego typu aplikacji. Jeśli na przykład tworzysz aplikację internetową, dodaj autoryzowane identyfikatory URI dla żądań przeglądarki i serwera.
  8. Po utworzeniu klienta zapisz identyfikator klienta i obiekt tajny.
  9. Podczas konfigurowania hosta MCP lub aplikacji Serwer MCP na potrzeby dostępu do Maps Grounding Lite podaj identyfikator klienta i tajny klucz klienta OAuth. Musisz też poprosić o ten zakres: https://www.googleapis.com/auth/maps-platform.mapstools.

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 do korzystania z interfejsów API Google.

Konfigurowanie LLM pod kątem dostępu do serwera MCP Maps Grounding Lite

Gdy masz projekt Google Cloud z włączoną usługą Maps Grounding Lite API i prawidłowymi danymi logowania, takimi jak klucz interfejsu API lub identyfikator klienta OAuth i tajny klucz, możesz skonfigurować LLM, aby uzyskiwały dostęp do serwera MCP. Aby to zrobić, postępuj zgodnie z odpowiednią dokumentacją konfiguracji MCP i użyj adresu URL serwera MCP Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Więcej informacji znajdziesz w artykule o konfigurowaniu MCP w aplikacji AI.

Konfigurowanie Grounding Lite w Mapach za pomocą interfejsu wiersza poleceń Gemini

W tej sekcji znajdziesz przykład konfigurowania serwera Maps Grounding Lite MCP za pomocą interfejsu wiersza poleceń Gemini. Więcej informacji znajdziesz w artykule na temat serwerów MCP z interfejsem wiersza poleceń Gemini.

  1. Po zainstalowaniu interfejsu wiersza poleceń Gemini możesz użyć polecenia add, aby skonfigurować serwer MCP 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

    Jeśli konfiguracja się powiodła, powinno pojawić się potwierdzenie, że serwer został dodany do ustawień użytkownika.

  2. Aby sprawdzić, czy serwer działa prawidłowo, uruchom polecenie /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

  3. Zacznij zadawać pytania dotyczące Map za pomocą interfejsu wiersza poleceń. Spróbuj na przykład powiedzieć „Poleć mi restauracje w Mountain View”, co powinno wywołać narzędzie search_places w Twoim imieniu.

Konfigurowanie Grounding Lite za pomocą pakietu Agent Development Kit (ADK)

W tej sekcji znajdziesz przykłady pokazujące, jak skonfigurować serwer Grounding Lite MCP za pomocą pakietu Agent Development Kit (ADK) i Pythona, Javy lub TypeScriptu.

Python

Pełną implementację tego przykładu znajdziesz na GitHubie w repozytorium adk-samples.

Krok 1. Zdefiniuj agenta za pomocą McpToolset na potrzeby Grounding Lite w Mapach Google

Zmodyfikuj plik agent.py. Zastąp YOUR_GOOGLE_MAPS_API_KEY swoim kluczem interfejsu API.

# ./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"
                }
            )
        )
    ]
)
Krok 2. Sprawdź, czy istnieje __init__.py

Upewnij się, że masz plik __init__.py w tym samym katalogu co plik agent.py:

from . import agent
Krok 3. Uruchom adk web i wejdź w interakcję
  1. Ustaw zmienną środowiskową:
    Ustaw klucz interfejsu API Map Google jako zmienną środowiskową w terminalu: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. Uruchom adk web:
    Uruchom to polecenie, aby uruchomić interfejs internetowy ADK: 
    adk web
  3. Interakcja w interfejsie:
    • Wybierz travel_planner_agent.
    • Wypróbuj prompty takie jak:
      • „Jutro będę w San Francisco. Jaka jest pogoda?”
      • „Znajdź kawiarnie w pobliżu parku Golden Gate”.
      • „Pokaż mi trasę dojazdu z Googleplexu na lotnisko Chopina”.

Java

Zdefiniuj agenta, który inicjuje McpToolset w języku Java. Jeśli nie używasz zmiennej środowiskowej, zastąp YOUR_GOOGLE_MAPS_API_KEY_HERE rzeczywistym kluczem interfejsu API.

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

Zdefiniuj agenta, który inicjuje MCPToolset w 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"
            }
        })
    ],
});

Przesyłanie opinii

Aby przesłać opinię o usłudze Grounding Lite w Mapach, użyj tych formularzy: