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

Maps Grounding Lite

Grounding Lite di Google Maps Platform è un servizio con supporto per Model Context Protocol (MCP) che semplifica il grounding delle applicazioni AI con dati geospaziali attendibili di Google Maps. Il server MCP fornisce strumenti che consentono agli LLM di accedere alle funzionalità per luoghi, meteo e percorsi. Puoi provare Grounding Lite di Maps attivandolo in qualsiasi strumento che supporti i server MCP.

Strumenti

Grounding Lite di Maps fornisce strumenti che consentono agli LLM di accedere alle seguenti funzionalità di Google Maps:

Cerca luoghi: richiedi informazioni sui luoghi e ottieni riepiloghi dei dati sui luoghi generati dall'AI, nonché ID luogo, coordinate di latitudine e longitudine e link di Google Maps per ciascuno dei luoghi inclusi nel riepilogo. Puoi utilizzare gli ID luogo e le coordinate di latitudine e longitudine restituiti con altre API di Google Maps Platform per mostrare i luoghi su una mappa.
Cerca meteo: richiedi informazioni sul meteo e restituisci le condizioni attuali, le previsioni orarie e le previsioni giornaliere.
Calcola percorsi: richiedi informazioni sui percorsi in auto o a piedi tra due località e restituisci informazioni sulla distanza e sulla durata del percorso.

Nota: Grounding Lite di Maps non fornisce informazioni su indicazioni stradali passo passo, indicazioni, traffico in tempo reale o navigazione.

L'abilitazione del server MCP di Grounding Lite di Maps consente agli LLM di chiamare i nuovi strumenti esposti dal server per restituire ulteriori informazioni di grounding per i tipi di dati elencati sopra. Sebbene l'LLM possa utilizzare queste informazioni aggiuntive per il contesto, la risposta che l'LLM genera in definitiva potrebbe non includere le informazioni esatte restituite dal server MCP. Devi verificare l'accuratezza della risposta generata.

Prova l'app di esempio di Grounding Lite di Maps (si apre in una nuova scheda)

Fatturazione e quote

Come vengono addebitati i costi

Con il modello di prezzi pagamento a consumo di Google Maps Platform, l'utilizzo di Grounding Lite di Maps viene calcolato per ogni richiesta, dove ogni richiesta rappresenta un evento di fatturazione. L'utilizzo viene monitorato per ogni SKU del prodotto. La fattura mostra una voce per ogni SKU, oltre agli addebiti totali. Per saperne di più, consulta la Panoramica dei report.

Per i dettagli sui prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.

Grounding Lite di Maps è disponibile anche tramite i pacchetti Essentials e Pro Subscribe to save.

Quote

Le seguenti quote si applicano agli strumenti forniti da Grounding Lite di Maps:

Cerca luoghi: 300 query al minuto per progetto.
Cerca meteo: 300 query al minuto per progetto.
Calcola percorsi: 300 query al minuto per progetto.

Norme e Termini di servizio

Grounding Lite di Maps è soggetto ai Termini di servizio di Google Maps Platform, inclusi i termini specifici del servizio per questo servizio. Questa sezione descrive i requisiti di utilizzo del servizio aggiuntivo per Grounding Lite di Maps, inclusi gli LLM compatibili e i requisiti di attribuzione della fonte.

Requisiti per gli LLM compatibili

Puoi utilizzare Grounding Lite di Maps solo con un LLM conforme ai Termini di servizio di Google Maps Platform.

Ad esempio, è tua responsabilità assicurarti che i contenuti di Google Maps non vengano memorizzati nella cache, archiviati o utilizzati per migliorare l'LLM che scegli di utilizzare. Prima di utilizzare Grounding Lite di Maps, dovrai esaminare i Termini di servizio per qualsiasi modello che intendi utilizzare con Grounding Lite di Maps. Non devi utilizzare Grounding Lite di Maps con modelli che utilizzano l'input di dati nel modello per l'addestramento o il miglioramento del modello. È tua responsabilità assicurarti che il tuo utilizzo del modello sia pienamente conforme alle limitazioni dei contenuti di Google Maps nei Termini di servizio di Google Maps Platform, inclusi i termini specifici del servizio.

Requisiti di attribuzione per le fonti di Google Maps

Ogni risposta dello strumento di Grounding Lite di Maps include le fonti. Quando presenti i risultati che utilizzano gli strumenti forniti da Grounding Lite di Maps, devi includere le fonti di Google Maps associate in modo da soddisfare i seguenti requisiti:

Le fonti di Google Maps devono seguire immediatamente i contenuti generati che supportano le fonti. Questi contenuti generati sono anche chiamati output di grounding.
Le fonti di Google Maps devono essere visualizzabili in un'unica interazione utente.

Fonti per lo strumento Cerca luoghi

Il campo places dello strumento search_places fornisce le fonti che supportano il summary. Per places, vengono restituiti i seguenti metadati:

place (nome della risorsa)
id
location
googleMapsLinks

Per ogni luogo, devi generare un'anteprima del link che soddisfi questi requisiti:

Attribuisci ogni fonte a Google Maps, seguendo le linee guida per l'attribuzione del testo di Grounding Lite di Maps.
Crea un link alla fonte utilizzando places.googleMapsLinks.placeUrl dalla risposta.

Configurare gli LLM per utilizzare il server MCP

Per utilizzare Grounding Lite di Maps, devi prima avere un progetto Google Cloud con il servizio API Grounding Lite di Maps abilitato, nonché una chiave API o un ID client OAuth. Poi, puoi configurare gli LLM per accedere al server MCP. Il server MCP di Grounding Lite utilizza il trasporto HTTP in streaming.

Abilitare il servizio Grounding Lite di Maps nel progetto Google Cloud

Per abilitare l'API nel progetto:

Nella console Google Cloud, scegli il progetto che vuoi utilizzare per Grounding Lite di Maps.
Abilita la fatturazione per il progetto nella console Google Cloud.
Abilita Grounding Lite di Maps nella Google Cloud libreria API della console.

Eseguire l'autenticazione utilizzando una chiave API

Puoi utilizzare una chiave API esistente con Grounding Lite di Maps o crearne una nuova, a condizione che tu abiliti il servizio API Grounding Lite di Maps sia nel progetto Google Cloud sia nella chiave.

Per eseguire l'autenticazione utilizzando una chiave API:

Crea o configura una chiave API seguendo i passaggi descritti in Inizia a utilizzare Google Maps Platform.
Passa la chiave al server MCP utilizzando l'intestazione X-Goog-Api-Key. Devi specificarla come intestazione HTTP personalizzata nella configurazione dello strumento MCP dell'LLM.

Eseguire l'autenticazione utilizzando OAuth

Puoi eseguire l'autenticazione utilizzando OAuth creando le credenziali OAuth e passandole all'host MCP o all'applicazione server MCP.

Per eseguire l'autenticazione utilizzando OAuth:

Nella console Google Cloud, scegli il progetto che vuoi utilizzare per Grounding Lite di Maps.
Nel menu API e servizi, seleziona Credenziali.
Nel menu in alto, seleziona Crea credenziali > ID client OAuth.
Se il progetto non ha una schermata per il consenso configurata, fai clic su Configura schermata per il consenso e segui le istruzioni sullo schermo.
Nella sezione Metriche, fai clic su Crea client OAuth.
Nella schermata Crea ID client OAuth, seleziona un tipo di applicazione e inserisci un nome per l'ID client.
Specifica i dettagli aggiuntivi pertinenti al tipo di applicazione. Ad esempio, se stai creando un'applicazione web, aggiungi gli URI autorizzati per le richieste del browser e del server.
Una volta creato il client, salva l'ID client e il segreto.
Quando configuri l'host MCP o l'applicazione server MCP per accedere a Grounding Lite di Maps, passa l'ID client OAuth e il segreto. Devi anche richiedere il seguente ambito: https://www.googleapis.com/auth/maps-platform.mapstools.

Per saperne di più, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Configurare gli LLM per accedere al server MCP di Grounding Lite di Maps

Una volta che hai un progetto cloud Google Cloud con il servizio API Grounding Lite di Maps abilitato e credenziali valide, come una chiave API o un ID client OAuth e un secret, puoi configurare gli LLM per accedere al server MCP seguendo la documentazione di configurazione MCP corrispondente e utilizzando l'URL del server MCP di Grounding Lite di Maps: https://mapstools.googleapis.com/mcp

Per saperne di più, consulta Configurare MCP in un'applicazione AI applicazione.

Configurare Grounding Lite di Maps con Gemini CLI

Questa sezione fornisce un esempio di come configurare il server MCP di Grounding Lite di Maps utilizzando la CLI di Gemini. Per maggiori dettagli, consulta la sezione Server MCP con Gemini CLI.

Dopo aver installato Gemini CLI, puoi utilizzare il comando add per configurare il server MCP di Grounding Lite di Maps:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
Se la configurazione è andata a buon fine, dovresti visualizzare una conferma che il server è stato aggiunto alle impostazioni utente.

Per verificare che il server funzioni correttamente, esegui il comando /mcp list:

> /mcp list

Configured MCP servers:

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

Inizia a porre domande relative a Maps con la CLI. Ad esempio, prova a dire "Consigliami alcuni ristoranti a Mountain View", che dovrebbe chiamare lo strumento search_places per tuo conto.

Configurare Grounding Lite con Agent Development Kit (ADK)

Questa sezione fornisce esempi che mostrano come configurare il server MCP di Grounding Lite utilizzando Agent Development Kit (ADK) e Python, Java o TypeScript.

Python

Passaggio 1: definisci l'agente con `McpToolset` per Grounding Lite di Google Maps

Modifica il file agent.py. Sostituisci YOUR_GOOGLE_MAPS_API_KEY con la tua chiave API effettiva.

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

Passaggio 2: assicurati che `init.py` esista

Assicurati di avere un __init__.py nella stessa directory di agent.py:

from . import agent

Passaggio 3: esegui `adk web` e interagisci

Imposta la variabile di ambiente:
imposta la chiave API di Google Maps come variabile di ambiente nel terminale:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Esegui adk web:
esegui il seguente comando per avviare l'interfaccia web ADK:
```
adk web
        
```
Interagisci nell'interfaccia utente:
- Seleziona travel_planner_agent.
- Prova prompt come:
  - "Domani sarò a San Francisco. Che tempo farà?"
  - "Trova caffetterie vicino al Golden Gate Park."
  - "Ottieni indicazioni stradali da GooglePlex a SFO."

Java

Definisci un agente che inizializza McpToolset in Java. Sostituisci YOUR_GOOGLE_MAPS_API_KEY_HERE con la chiave API effettiva che hai ottenuto se non utilizzi una variabile di ambiente.

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

Definisci un agente che inizializza MCPToolset in 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"
            }
        })
    ],
});

Condividere feedback

Per condividere il tuo feedback su Grounding Lite di Maps, utilizza i seguenti moduli: