Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

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 AI za pomocą zaufanych danych geoprzestrzennych z Map Google. Serwer MCP udostępnia narzędzia, które umożliwiają dużym modelom językowym dostęp do funkcji związanych z miejscami, pogodą i trasami oraz przekształcanie nazw lokalizacji i adresów URL Map Google w identyfikatory 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: prośba o informacje o miejscach i uzyskiwanie wygenerowanych przez AI podsumowań danych o miejscach, a także identyfikatorów miejsc, współrzędnych geograficznych oraz linków 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 wykorzystać w innych interfejsach API Google Maps Platform, aby wyświetlać miejsca na mapie.
Sprawdzanie pogody: wysyłanie prośby o informacje o pogodzie i zwracanie aktualnych warunków, prognoz godzinowych i prognoz dziennych.
Obliczanie tras: prośba o informacje o trasach przejazdu samochodem lub przejścia pieszo między 2 lokalizacjami oraz zwracanie informacji o odległości i czasie trwania trasy.

Uwaga: usługa Maps Grounding Lite nie udostępnia szczegółowych wskazówek dojazdu, informacji o natężeniu ruchu w czasie rzeczywistym ani danych nawigacyjnych.
Rozwiązywanie nazw i rozwiązywanie adresów URL Map Google: rozwiązywanie nazw lokalizacji, adresów i adresów URL Map Google na identyfikatory miejsc. Więcej informacji znajdziesz w artykule na temat interfejsu Resolution API.

Włączenie serwera MCP Maps Grounding Lite umożliwia dużym modelom językowym wywoływanie nowych narzędzi udostępnianych przez serwer w celu zwracania dodatkowych informacji o podstawach dla wymienionych powyżej typów danych. Chociaż LLM może używać tych dodatkowych informacji jako kontekstu, wygenerowana przez niego odpowiedź 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 dowolnej formie 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 MCP usługi Maps Grounding Lite:

Resolve names (REST, MCP): przekształcanie partii nazw lokalizacji lub adresów w konkretne obiekty miejsc w Mapach Google. Jest to przydatne do przekształcania nieustrukturyzowanych zapytań użytkowników w stabilne identyfikatory miejsc.
Resolve Maps URLs (REST, MCP): przekształca grupę adresów URL Map Google w konkretne obiekty miejsc. Obsługiwane formaty to standardowe adresy URL miejsc i skrócone adresy URL.

Zwrócone identyfikatory miejsc możesz wykorzystać w innych interfejsach API Google Maps Platform. Każda odpowiedź zawiera też link, który zapisuje rozpoznane miejsca jako listę w Mapach Google.

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

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

Rozliczenia i limity

Jak są naliczane opłaty

W modelu płatności według wykorzystania Google Maps Platform korzystanie z usługi Maps Grounding Lite jest obliczane dla każdego żądania, przy czym każde żądanie stanowi zdarzenie rozliczeniowe. Wykorzystanie jest śledzone dla każdego kodu SKU usługi. Na rachunku znajduje się pozycja dla każdego kodu SKU oraz łączne opłaty. 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 – podstawowe zasady dotyczące wyszukiwarki (tylko identyfikatory).

Mapy z użyciem Grounding Lite są też dostępne w pakietach Essentials i Pro. Subskrybuj, aby zaoszczędzić

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.
Sprawdzanie pogody: 300 zapytań na minutę na projekt.
Obliczanie tras: 300 zapytań na minutę na projekt.
Rozwiązywanie nazw: 600 zapytań na minutę na projekt.
Rozwiązywanie adresów URL Map Google: 600 zapytań na minutę na projekt.

Każde żądanie interfejsu Resolution API jest traktowane jako jedno zapytanie, niezależnie od liczby elementów, które zawiera.

Zasady i warunki korzystania z usługi

Usługa Maps Grounding Lite podlega Warunkom korzystania z usługi Google Maps Platform, w tym szczegółowym warunkom korzystania z tej usługi. Ta sekcja zawiera opis dodatkowych wymagań dotyczących korzystania z usługi Maps Grounding Lite, w tym zgodnych dużych modeli językowych i wymagań dotyczących atrybucji źródła.

Wymagania dotyczące zgodnych dużych modeli językowych

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

Na przykład ponosisz odpowiedzialność za to, aby treści z Map Google nie były buforowane, przechowywane ani wykorzystywane do ulepszania wybranego przez Ciebie dużego modelu językowego. Zanim zaczniesz korzystać z Grounding Lite w Mapach, musisz zapoznać się z Warunkami korzystania z usługi dotyczącymi każdego modelu, którego zamierzasz używać z Grounding Lite w Mapach. Nie możesz używać Maps Grounding Lite z modelami, które wykorzystują dane wejściowe do trenowania lub ulepszania modeli. Ponosisz odpowiedzialność za zapewnienie, że korzystanie z modelu jest w pełni zgodne z ograniczeniami dotyczącymi treści w Mapach Google określonymi w Warunkach korzystania z usługi Google Maps Platform, w tym w warunkach korzystania z konkretnych usług.

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

Każda odpowiedź narzędzia w usłudze Maps Grounding Lite 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 obsługują. Wygenerowane treści są też nazywane odpowiedzią opartą na faktach.
Źródła Map Google muszą być widoczne w ramach jednej interakcji użytkownika.

Źródła narzędzia Wyszukaj miejsca

Pole search_places narzędzia places zawiera źródła potwierdzające 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:

Każde źródło przypisuj do Map Google zgodnie z wytycznymi dotyczącymi przypisywania tekstów w Mapach Grounding Lite.
Połącz się ze źródłem za pomocą places.googleMapsLinks.placeUrl z odpowiedzi.

Konfigurowanie dużych modeli językowych do 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 API lub identyfikator klienta OAuth. Następnie możesz skonfigurować duże modele językowe, aby miały dostęp do serwera MCP. Serwer Grounding Lite MCP korzysta z transportu HTTP z możliwością przesyłania strumieniowego.

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

Aby włączyć interfejs API w projekcie:

W konsoli Google Cloud wybierz projekt, którego chcesz użyć w usłudze Maps Grounding Lite.
Włącz rozliczenia w projekcie w konsoli Google Cloud.
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 interfejsem Maps Grounding Lite lub utworzyć nowy, o ile włączysz usługę interfejsu Maps Grounding Lite w projekcie w chmurze Google Cloud i na kluczu.

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

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

Uwierzytelnianie za pomocą OAuth

Do uwierzytelniania możesz używać protokołu OAuth, tworząc dane uwierzytelniające OAuth i przekazując je do hosta MCP lub aplikacji serwera MCP.

Aby uwierzytelnić się za pomocą protokołu OAuth:

W konsoli Google Cloud wybierz projekt, którego chcesz użyć w usłudze Maps Grounding Lite.
W menu Interfejsy API i usługi wybierz Dane logowania.
W górnym menu 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 Tworzenie identyfikatora klienta OAuth wybierz typ aplikacji i wpisz nazwę identyfikatora klienta.
Podaj dodatkowe informacje, które są istotne w przypadku Twojego typu zgłoszenia. Jeśli na przykład tworzysz aplikację internetową, dodaj autoryzowane identyfikatory URI dla żą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 Maps Grounding Lite przekaż identyfikator 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 dużych modeli językowych w celu uzyskania dostępu do serwera MCP Maps Grounding Lite

Gdy masz już 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 klucz tajny, możesz skonfigurować LLM, aby uzyskiwać dostęp do serwera MCP. W tym celu 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 Konfigurowanie MCP w aplikacji AI.

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

W tej sekcji znajdziesz przykład konfiguracji serwera MCP Maps Grounding Lite 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 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, zobaczysz potwierdzenie, że serwer został dodany do ustawień użytkownika.

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

Zacznij zadawać pytania dotyczące Map za pomocą interfejsu wiersza poleceń. Możesz na przykład powiedzieć „Poleć mi jakieś restauracje w Warszawie”, co powinno spowodować wywołanie narzędzia 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 MCP Grounding Lite przy użyciu pakietu Agent Development Kit (ADK) i języka Python, Java lub TypeScript.

Python

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

Krok 1. Zdefiniuj agenta za pomocą funkcji `McpToolset` w usłudze Grounding Lite w ramach Map 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 element `init.py`

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

from . import agent

Krok 3. Uruchom `adk web` i interaguj

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:
Aby uruchomić interfejs internetowy ADK, wykonaj to polecenie:
```
adk web
        
```
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 Golden Gate Park”.
  - „Wyznacz trasę z GooglePlex do SFO”.

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 uzyskanym 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, skorzystaj z tych formularzy: