Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Maps Grounding Lite

Google Maps Platform Grounding Lite to usługa obsługująca protokół Model Context Protocol (MCP), która ułatwia oparcie aplikacji AI na faktach za pomocą zaufanych danych geoprzestrzennych z Map Google. Serwer MCP udostępnia narzędzia, które umożliwiają LLM dostęp do funkcji dotyczących miejsc, pogody i tras. Możesz wypróbować Grounding Lite w ramach Map Google, włączając go w dowolnym narzędziu obsługującym serwery MCP.

Narzędzia

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

Wyszukiwanie Miejsc: wysyłaj zapytania o informacje o Miejscach i otrzymuj wygenerowane przez AI podsumowania danych o Miejscach, a także identyfikatory miejsc, współrzędne geograficzne oraz linki do Map Google dla każdego Miejsca uwzględnionego w podsumowaniu. Zwrócone identyfikatory miejsc oraz współrzędne geograficzne możesz wykorzystać w innych interfejsach API Google Maps Platform, aby wyświetlać miejsca na mapie.
Sprawdzanie pogody: wysyłaj zapytania o informacje o pogodzie i otrzymuj aktualne warunki, prognozy godzinowe i prognozy dzienne.
Obliczanie tras: wysyłaj zapytania o informacje o trasach samochodowych lub pieszych między 2 lokalizacjami i otrzymuj informacje o odległości i czasie trwania trasy.

Uwaga:Grounding Lite w ramach Map Google nie udostępnia szczegółowych wskazówek dojazdu, informacji o natężeniu ruchu w czasie rzeczywistym ani informacji o nawigacji.

Włączenie serwera MCP Grounding Lite w ramach Map Google umożliwia LLM wywoływanie nowych narzędzi udostępnianych przez serwer w celu zwracania dodatkowych informacji o groundingu dla wymienionych powyżej typów danych. Chociaż LLM może używać tych dodatkowych informacji w kontekście, odpowiedź, którą ostatecznie wygeneruje, może nie zawierać dokładnych informacji zwróconych przez serwer MCP. Powinieneś sprawdzić dokładność wygenerowanej odpowiedzi.

Resolution API (wersja eksperymentalna)

Grounding Lite w ramach Map Google udostępnia Resolution API, które umożliwia przekształcanie tekstu i adresów URL w dowolnym formacie na uporządkowane identyfikatory miejsc w Mapach Google. Resolution API składa się z 2 punktów końcowych:

Resolve names: przekształca grupę nazw lub adresów lokalizacji na konkretne obiekty miejsc w Mapach Google. Jest to przydatne do groundingu nieustrukturyzowanych zapytań użytkowników na stabilne identyfikatory miejsc.
Rozwiąż adresy URL Map: Przekształca grupę adresów URL Map Google na konkretne obiekty miejsc. Obsługiwane formaty to standardowe adresy URL miejsc i skrócone adresy URL.

Te punkty końcowe można wykorzystać do groundingu nieustrukturyzowanych zapytań użytkowników lub linków na stabilne identyfikatory miejsc w celu integracji z innymi interfejsami API Google Maps Platform.

Więcej informacji znajdziesz w artykule Resolution API (wersja eksperymentalna) w ramach narzędzi Map Google.

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

Płatności i limity

Jak naliczane są opłaty

W modelu płatności według wykorzystania Google Maps Platform korzystanie z Grounding Lite w ramach Map Google jest obliczane na podstawie każdego żądania, a każde żądanie stanowi zdarzenie rozliczeniowe. Wykorzystanie jest śledzone w przypadku każdego produktu SKU. Na fakturze oprócz łącznych opłat widnieje pozycja dla każdego kodu SKU. Więcej informacji znajdziesz w artykule Omówienie raportowania.

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

Grounding Lite w ramach Map Google jest też dostępny w ramach pakietów subskrypcji Essentials i Pro Subscribe to save.

Limity

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

Wyszukiwanie miejsc: 300 zapytań na minutę na projekt.
Sprawdzanie pogody: 300 zapytań na minutę na projekt.
Obliczanie tras: 300 zapytań na minutę na projekt.
Resolve names (wersja eksperymentalna): 600 zapytań na minutę na projekt.
Resolve Maps URLs (wersja eksperymentalna): 600 zapytań na minutę na projekt.

Zasady i warunki korzystania z usługi

Grounding Lite w ramach Map Google podlega Warunkom korzystania z usługi Google Maps Platform, w tym dodatkowym warunkom korzystania z tej usługi. W tej sekcji opisujemy wymagania dotyczące korzystania z usługi dodatkowej Grounding Lite w ramach Map Google, w tym wymagania dotyczące zgodnych LLM i podania źródła.

Wymagania dotyczące zgodnych LLM

Grounding Lite w ramach Map Google możesz używać tylko z LLM, które są zgodne z Warunkami korzystania z usługi Google Maps Platform.

Odpowiadasz np. za to, aby treści z Map Google nie były buforowane, przechowywane ani wykorzystywane do ulepszania LLM, którego używasz. Zanim zaczniesz korzystać z Grounding Lite w ramach Map Google, musisz zapoznać się z Warunkami korzystania z usługi dotyczącymi każdego modelu, którego zamierzasz używać z tą usługą. Nie możesz używać Grounding Lite w ramach Map Google z żadnymi modelami, które wykorzystują dane wejściowe do trenowania lub ulepszania modelu. Odpowiadasz za to, aby korzystanie z modelu było w pełni zgodne z ograniczeniami dotyczącymi treści z Map Google określonymi w Warunkach korzystania z usługi Google Maps Platform, w tym w dodatkowych warunkach korzystania z usługi.

Wymagania dotyczące atrybucji źródeł z Map Google

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

Źródła z Map Google muszą znajdować się bezpośrednio po wygenerowanej treści, którą obsługują. Ta wygenerowana treść jest też nazywana wynikiem z groundingiem.
Źródła z Map Google muszą być widoczne w ramach jednej interakcji użytkownika.

Źródła narzędzia Wyszukiwanie miejsc

Pole places narzędzia search_places zawiera źródła, które obsługują 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:

Przypisz każde źródło do Map Google, zgodnie z wytycznymi dotyczącymi atrybucji tekstowej Grounding Lite w ramach Map Google.
Połącz się ze źródłem za pomocą places.googleMapsLinks.placeUrl z odpowiedzi.

Konfigurowanie LLM do korzystania z serwera MCP

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

Włączanie usługi Maps Grounding Lite w projekcie Google Cloud

Aby włączyć interfejs API w projekcie:

W konsoli Google Cloud wybierz projekt, którego chcesz używać w Grounding Lite w ramach Map Google.
Włącz płatności w projekcie w konsoli Google Cloud.
Włącz Grounding Lite w ramach Map Google w bibliotece interfejsów API konsoli Google Cloud.

Uwierzytelnianie za pomocą klucza interfejsu API

Możesz użyć istniejącego klucza interfejsu API z Grounding Lite w ramach Map Google 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:

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

Uwierzytelnianie za pomocą OAuth

Możesz uwierzytelnić się za pomocą OAuth, tworząc dane logowania OAuth i przekazując je do hosta MCP lub aplikacji serwera MCP.

Aby uwierzytelnić się za pomocą OAuth:

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

Więcej informacji znajdziesz w artykule Używanie OAuth 2.0 do korzystania z interfejsów API Google.

Konfigurowanie LLM do uzyskiwania dostępu do serwera MCP Grounding Lite w ramach Map Google

Gdy masz projekt w chmurze Google Cloud z włączoną usługą Maps Grounding Lite API i prawidłowe dane logowania, takie jak klucz interfejsu API lub identyfikator klienta OAuth i obiekt tajny, możesz skonfigurować LLM tak, aby miały dostęp do serwera MCP. W tym celu postępuj zgodnie z odpowiednią dokumentacją konfiguracji MCP i użyj adresu URL serwera MCP Grounding Lite w ramach Map Google: https://mapstools.googleapis.com/mcp

Więcej informacji znajdziesz w artykule Konfigurowanie MCP w aplikacji AI application.

Konfigurowanie Grounding Lite w ramach Map Google za pomocą interfejsu wiersza poleceń Gemini

W tej sekcji znajdziesz przykład konfigurowania serwera MCP Grounding Lite w ramach Map Google za pomocą interfejsu wiersza poleceń Gemini. Więcej informacji znajdziesz w artykule Serwery MCP z interfejsem wiersza poleceń Gemini.

Po zainstalowaniu interfejsu wiersza poleceń Gemini możesz użyć polecenia add, aby skonfigurować serwer MCP Grounding Lite w ramach Map Google:
```
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ę uda, zobaczysz potwierdzenie, że serwer został dodany do ustawień użytkownika.

Aby sprawdzić, czy serwer działa prawidłowo, uruchom polecenie /mcp list:

> /mcp list

Configured MCP servers:

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

Zacznij zadawać pytania związane z Mapami za pomocą interfejsu wiersza poleceń. Spróbuj np. wpisać „Poleć mi jakieś restauracje w Mountain View”. Powinno to wywołać narzędzie search_places w Twoim imieniu.

Konfigurowanie Grounding Lite w ramach Map Google za pomocą pakietu Agent Development Kit (ADK)

W tej sekcji znajdziesz przykłady pokazujące, jak skonfigurować serwer MCP Grounding Lite za pomocą pakietu Agent Development Kit (ADK) i języka Python, Java lub TypeScript.

Python

Krok 1. Zdefiniuj agenta za pomocą `McpToolset` na potrzeby Grounding Lite w ramach Map Google

Zmodyfikuj plik agent.py. Zastąp YOUR_GOOGLE_MAPS_API_KEY rzeczywistym 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 plik `init.py`

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

from . import agent

Krok 3. Uruchom `adk web` i wejdź w interakcję

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"
        
```
Uruchom adk web:
Uruchom to polecenie, aby otworzyć interfejs ADK:
```
adk web
        
```
Wejdź w interakcję w interfejsie:
- Wybierz travel_planner_agent.
- Wypróbuj te prompty:
  - „Jutro będę w San Francisco. Jaka będzie pogoda?”
  - „Znajdź kawiarnie w pobliżu Golden Gate Park”.
  - „Wyznacz trasę z GooglePlex do SFO”.

Java

Zdefiniuj agenta, który inicjuje McpToolset w Javie. Jeśli nie używasz zmiennej środowiskowej, zastąp YOUR_GOOGLE_MAPS_API_KEY_HERE rzeczywistym kluczem interfejsu API uzyskanym przez Ciebie.

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 Grounding Lite w ramach Map Google, użyj tych formularzy: