Maps Grounding Lite

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

Strumenti

Maps Grounding Lite fornisce strumenti che consentono ai 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 visualizza le condizioni attuali, le previsioni orarie e quelle giornaliere.

• Calcola itinerari: richiedi informazioni sugli itinerari in auto o a piedi tra due località e restituisci informazioni sulla distanza e la durata dell'itinerario.

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

API Resolution (sperimentale)

Maps Grounding Lite fornisce l'API Resolution, che consente di risolvere testo e URL di località in formato libero in identificatori di luoghi strutturati di Google Maps. L'API Resolution è costituita da due endpoint:

• Risolvi nomi: Risolvi un batch di nomi di località o indirizzi in entità di luoghi specifici su Google Maps. Ciò è utile per basare le query degli utenti non strutturate su ID luogo stabili.
• Risolvi URL di Maps: Risolvi un batch di URL di Google Maps in entità di luoghi specifici. I formati supportati includono URL di luoghi standard e URL abbreviati.

Questi endpoint possono essere utilizzati per basare query o link utente non strutturati su ID luogo stabili per l'integrazione con altre API di Google Maps Platform.

Per saperne di più, consulta la sezione API Maps Tools Resolution (sperimentale).

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

Fatturazione e quote

Modalità di fatturazione

Con il modello di determinazione dei prezzi pagamento a consumo di Google Maps Platform, l'utilizzo di Maps Grounding Lite viene calcolato per ogni richiesta, dove ogni richiesta rappresenta un evento di fatturazione. L'utilizzo viene monitorato per ogni SKU 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.

Maps Grounding Lite è disponibile anche nei pacchetti Essentials e Pro Abbonati per risparmiare.

Quote

Le seguenti quote si applicano agli strumenti e alle API forniti da Maps Grounding Lite:

• Cerca luoghi: 300 query al minuto per progetto.
• Cerca meteo: 300 query al minuto per progetto.
• Calcola itinerari: 300 query al minuto per progetto.
• Risolvi nomi (sperimentale): 600 query al minuto per progetto.
• Risolvi URL di Maps (sperimentale): 600 query al minuto per progetto.

Norme e Termini di servizio

Maps Grounding Lite è soggetto ai Termini di servizio di Google Maps Platform, inclusi i termini specifici del servizio per questo servizio. Questa sezione descrive i requisiti aggiuntivi per l'utilizzo del servizio Maps Grounding Lite, inclusi i LLM compatibili e i requisiti di attribuzione delle fonti.

Requisiti per i LLM compatibili

Puoi utilizzare Maps Grounding Lite 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 il modello linguistico di grandi dimensioni che scegli di utilizzare. Prima di utilizzare Maps Grounding Lite, devi esaminare i Termini di servizio per qualsiasi modello che intendi utilizzare con Maps Grounding Lite. Non devi utilizzare Maps Grounding Lite con modelli che utilizzano i dati inseriti nel modello per l'addestramento o il miglioramento del modello. È tua responsabilità assicurarti che il tuo utilizzo del modello sia pienamente conforme alle limitazioni relative ai 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 Maps Grounding Lite include le fonti. Quando presenti risultati che utilizzano strumenti forniti da Maps Grounding Lite, 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 fondato.
• Le fonti di Google Maps devono essere visualizzabili in una sola interazione dell'utente.

Fonti per lo strumento Cerca luoghi

Il campo search_places dello places strumento fornisce fonti a sostegno del 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 i seguenti requisiti:

• Attribuisci ogni fonte a Google Maps, seguendo le linee guida per l'attribuzione del testo di Maps Grounding Lite.
• Collega la fonte utilizzando places.googleMapsLinks.placeUrl dalla risposta.

Configurare gli LLM per l'utilizzo del server MCP

Per utilizzare Maps Grounding Lite, devi prima disporre di un progetto Google Cloud con il servizio API Maps Grounding Lite abilitato, nonché di una chiave API o di un ID client OAuth. A questo punto, puoi configurare i LLM per accedere al server MCP. Il server MCP Grounding Lite utilizza il trasporto HTTP trasmissibile.

Abilita il servizio Maps Grounding Lite nel tuo progetto Google Cloud

Per abilitare l'API sul tuo progetto:

1. Nella console Google Cloud, scegli il progetto che vuoi utilizzare per Maps Grounding Lite.
2. Abilita la fatturazione per il progetto nella console Google Cloud.
3. Attiva Maps Grounding Lite nella libreria API di Google Cloud Console.

Autenticarsi utilizzando una chiave API

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

Per autenticarti utilizzando una chiave API:

1. Crea o configura una chiave API seguendo i passaggi descritti nella sezione Guida introduttiva a Google Maps Platform.
2. Trasferisci la chiave al server MCP utilizzando l'intestazione X-Goog-Api-Key. Devi specificarlo come intestazione HTTP personalizzata nella configurazione dello strumento MCP dell'LLM.

Eseguire l'autenticazione utilizzando OAuth

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

Per eseguire l'autenticazione utilizzando OAuth:

1. Nella console Google Cloud, scegli il progetto che vuoi utilizzare per Maps Grounding Lite.
2. Nel menu API e servizi, seleziona Credenziali.
3. Nel menu in alto, seleziona Crea credenziali > ID client OAuth.
4. 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.
5. Nella sezione Metriche, fai clic su Crea client OAuth.
6. Nella schermata Crea ID client OAuth, seleziona un tipo di applicazione e inserisci un nome per l'ID client.
7. Specifica i dettagli aggiuntivi pertinenti al tipo di applicazione. Ad esempio, se stai creando un'applicazione web, aggiungi URI autorizzati per richieste del browser e del server.
8. Una volta creato il client, salva l'ID client e il client secret.
9. Quando configuri l'applicazione host MCP o server MCP per accedere a Maps Grounding Lite, trasmetti 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.

Configura i LLM per accedere al server MCP Maps Grounding Lite

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

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

Configurare Maps Grounding Lite con Gemini CLI

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

1. Dopo aver installato Gemini CLI, puoi utilizzare il comando add per configurare il server 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
   

   Se la configurazione è andata a buon fine, dovresti visualizzare una conferma che il server è stato aggiunto alle impostazioni utente.

2. 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
   

3. Inizia a porre domande relative a Maps con la CLI. Ad esempio, prova a dire "Consigliami dei 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 Grounding Lite utilizzando l'Agent Development Kit (ADK) e Python, Java o TypeScript.

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

Condividere feedback

Per condividere un feedback su Maps Grounding Lite, utilizza i seguenti moduli:

• Segnala un bug
• Invia una richiesta di funzionalità
• Inviare un feedback