Maps Grounding Lite

Google Maps Platform Grounding Lite adalah layanan dengan dukungan Model Context Protocol (MCP) yang memudahkan Anda untuk membumikan aplikasi AI dengan data geospasial tepercaya dari Google Maps. Server MCP menyediakan alat yang memungkinkan LLM mengakses kemampuan untuk tempat, cuaca, dan rute. Anda dapat mencoba Maps Grounding Lite dengan mengaktifkannya di alat apa pun yang mendukung server MCP.

Alat

Maps Grounding Lite menyediakan alat yang memungkinkan LLM mengakses kemampuan Google Maps berikut:

• Menelusuri tempat: Meminta informasi tentang tempat dan mendapatkan ringkasan data tempat yang dibuat AI, serta ID Tempat, koordinat garis lintang dan garis bujur, dan link Google Maps untuk setiap tempat yang disertakan dalam ringkasan. Anda dapat menggunakan ID Tempat dan koordinat garis lintang dan garis bujur yang ditampilkan dengan Google Maps Platform API lainnya untuk menampilkan tempat di peta.
• Mencari cuaca: Meminta informasi tentang cuaca dan menampilkan kondisi saat ini, prakiraan per jam, dan prakiraan harian.

• Menghitung rute: Meminta informasi tentang rute mengemudi atau berjalan kaki antara dua lokasi dan menampilkan informasi jarak dan durasi rute.

  Catatan: Maps Grounding Lite tidak memberikan informasi rute, petunjuk arah, lalu lintas real-time, atau navigasi langkah demi langkah.

Mengaktifkan server MCP Maps Grounding Lite memungkinkan LLM memanggil alat baru yang diekspos oleh server untuk menampilkan informasi grounding tambahan untuk jenis data yang tercantum di atas. Meskipun LLM dapat menggunakan informasi tambahan ini untuk konteks, respons yang pada akhirnya dihasilkan LLM mungkin tidak menyertakan informasi persis yang ditampilkan oleh server MCP. Anda harus memverifikasi akurasi respons yang dihasilkan.

Mencoba aplikasi contoh Maps Grounding Lite (Buka di tab baru)

Penagihan dan kuota

Cara penagihan

Dengan model harga bayar sesuai penggunaan Google Maps Platform, penggunaan Maps Grounding Lite dihitung untuk setiap permintaan, dengan setiap permintaan mewakili satu peristiwa penagihan. Penggunaan dilacak untuk setiap produk SKU. Tagihan Anda menampilkan item baris untuk setiap SKU selain total biaya. Lihat Ringkasan pelaporan untuk mengetahui informasi selengkapnya.

Lihat Tabel harga utama dan Tabel harga India untuk mengetahui detail harga.

Maps Grounding Lite juga ditawarkan melalui paket Essentials dan Pro Subscribe to save.

Kuota

Kuota berikut berlaku untuk alat yang disediakan oleh Maps Grounding Lite:

• Menelusuri tempat: 300 kueri per menit, per project.
• Mencari cuaca: 300 kueri per menit, per project.
• Menghitung rute: 300 kueri per menit, per project.

Kebijakan dan persyaratan layanan

Maps Grounding Lite tunduk pada Persyaratan Layanan Google Maps Platform, termasuk persyaratan khusus layanan untuk layanan ini. Bagian ini menjelaskan persyaratan penggunaan layanan tambahan untuk Maps Grounding Lite, termasuk LLM yang kompatibel dan persyaratan atribusi sumber.

Persyaratan untuk LLM yang Kompatibel

Anda hanya dapat menggunakan Maps Grounding Lite dengan LLM yang mematuhi Persyaratan Layanan Google Maps Platform.

Misalnya, Anda bertanggung jawab untuk memastikan bahwa Konten Google Maps tidak di-cache, disimpan, atau digunakan untuk meningkatkan kualitas LLM yang Anda pilih untuk digunakan. Sebelum menggunakan Maps Grounding Lite, Anda harus meninjau Persyaratan Layanan untuk model apa pun yang ingin Anda gunakan dengan Maps Grounding Lite. Anda tidak boleh menggunakan Maps Grounding Lite dengan model apa pun yang menggunakan input data ke dalam model untuk pelatihan atau peningkatan model. Anda bertanggung jawab untuk memastikan bahwa penggunaan model Anda sepenuhnya mematuhi batasan pada Konten Google Maps dalam Persyaratan Layanan Google Maps Platform, termasuk persyaratan khusus layanan.

Persyaratan atribusi untuk sumber Google Maps

Setiap respons alat dari Maps Grounding Lite menyertakan sumber. Saat menampilkan hasil yang menggunakan alat yang disediakan oleh Maps Grounding Lite, Anda harus menyertakan sumber Google Maps terkait dengan cara yang memenuhi persyaratan berikut:

• Sumber Google Maps harus segera mengikuti konten yang dihasilkan yang didukung oleh sumber. Konten yang dihasilkan ini juga disebut sebagai Output yang Didasarkan.
• Sumber Google Maps harus dapat dilihat dalam satu interaksi pengguna.

Sumber untuk alat Menelusuri tempat

Kolom places alat search_places menyediakan sumber yang mendukung summary. Untuk places, metadata berikut akan ditampilkan:

• place (nama resource)
• id
• location
• googleMapsLinks

Untuk setiap tempat, Anda harus membuat pratinjau link yang memenuhi persyaratan ini:

• Atribusikan setiap sumber ke Google Maps, com as seguintes diretrizes de atribuição de texto do Maps Grounding Lite.
• Tautkan ke sumber menggunakan places.googleMapsLinks.placeUrl dari respons.

Mengonfigurasi LLM untuk menggunakan server MCP

Untuk menggunakan Maps Grounding Lite, Anda memerlukan project Google Cloud dengan layanan API Maps Grounding Lite yang diaktifkan, serta kunci API atau client ID OAuth. Kemudian, Anda dapat mengonfigurasi LLM untuk mengakses server MCP. Server MCP Grounding Lite menggunakan transpor HTTP yang Dapat Di-streaming.

Mengaktifkan layanan Maps Grounding Lite di project Google Cloud

Untuk mengaktifkan API di project Anda:

1. Di Konsol Google Cloud, pilih project yang ingin Anda gunakan untuk Maps Grounding Lite.
2. Aktifkan penagihan untuk project di Google Cloud Console.
3. Aktifkan Maps Grounding Lite di Google Cloud Library API Konsol.

Melakukan autentikasi menggunakan kunci API

Anda dapat menggunakan kunci API yang ada dengan Maps Grounding Lite atau membuat kunci baru, selama Anda mengaktifkan layanan API Maps Grounding Lite di project Google Cloud dan kunci.

Catatan: Untuk pengujian dan pembuatan prototipe, Anda juga dapat menggunakan Kunci Demo Maps tanpa biaya tanpa menyiapkan akun penagihan.

Untuk melakukan autentikasi menggunakan kunci API:

1. Buat atau konfigurasi kunci API dengan mengikuti langkah-langkah di Memulai dengan Google Maps Platform.
2. Teruskan kunci ke server MCP menggunakan header X-Goog-Api-Key. Anda harus menentukannya sebagai header HTTP kustom dalam konfigurasi alat MCP LLM.

Catatan: Saat membuat atau mengonfigurasi kunci API, pastikan untuk membatasi penggunaan kunci dengan menerapkan batasan yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Membatasi kunci API keys.

Melakukan autentikasi menggunakan OAuth

Anda dapat melakukan autentikasi menggunakan OAuth dengan membuat kredensial OAuth dan meneruskannya ke host MCP atau aplikasi server MCP.

Untuk melakukan autentikasi menggunakan OAuth:

1. Di Konsol Google Cloud, pilih project yang ingin Anda gunakan untuk Maps Grounding Lite.
2. Di menu API &Layanan, pilih Kredensial.
3. Di menu atas, pilih Buat kredensial > ID klien OAuth.
4. Jika project tidak memiliki layar izin yang dikonfigurasi, klik Konfigurasi layar izin dan ikuti petunjuk di layar.
5. Di bagian Metrik, klik Buat klien OAuth.
6. Di layar Buat ID klien OAuth, pilih jenis aplikasi dan masukkan nama untuk client ID.
7. Tentukan detail tambahan yang relevan dengan jenis aplikasi Anda. Misalnya, jika Anda membuat aplikasi web, tambahkan URI yang diotorisasi untuk permintaan browser dan server.
8. Setelah klien dibuat, simpan client ID dan rahasia klien.
9. Saat mengonfigurasi host MCP atau aplikasi server MCP untuk mengakses Maps Grounding Lite, teruskan client ID dan rahasia klien OAuth Anda. Anda juga harus meminta cakupan berikut: https://www.googleapis.com/auth/maps-platform.mapstools.

Untuk mengetahui informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Mengonfigurasi LLM untuk mengakses server MCP Maps Grounding Lite

Setelah memiliki project Google Cloud dengan layanan Maps Grounding Lite API yang diaktifkan dan kredensial yang valid, seperti kunci API atau client ID dan rahasia klien OAuth, Anda dapat mengonfigurasi LLM untuk mengakses server MCP dengan mengikuti dokumentasi konfigurasi MCP yang sesuai dan menggunakan URL server MCP Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi MCP di aplikasi AI.

Mengonfigurasi Maps Grounding Lite dengan Gemini CLI

Bagian ini memberikan contoh cara mengonfigurasi server MCP Maps Grounding Lite menggunakan Gemini CLI. Untuk mengetahui detail selengkapnya, lihat Server MCP dengan Gemini CLI.

1. Setelah menginstal Gemini CLI, Anda dapat menggunakan perintah add untuk mengonfigurasi 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
   

   Jika konfigurasi berhasil, Anda akan melihat konfirmasi bahwa server telah ditambahkan ke setelan pengguna.

2. Untuk memvalidasi bahwa server berfungsi dengan benar, jalankan perintah /mcp list:

   > /mcp list
   
   Configured MCP servers:
   
   maps-grounding-lite-mcp - Ready (3 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   search_places
   

3. Mulai ajukan pertanyaan terkait Maps dengan CLI. Misalnya, coba "Recommend me some restaurants in Mountain View" yang akan memanggil alat search_places atas nama Anda.

Catatan: Untuk mengetahui informasi tentang cara mengonfigurasi ekstensi Gemini CLI untuk mengakses Maps Grounding Lite menggunakan OAuth, lihat bagian Gemini CLI di dokumentasi MCP di Google Cloud.

Mengonfigurasi Grounding Lite dengan Agent Development Kit (ADK)

Bagian ini memberikan contoh yang menunjukkan cara mengonfigurasi server MCP Grounding Lite menggunakan Agent Development Kit (ADK) dan Python, Java, atau TypeScript.

Catatan: Pastikan Anda telah mengaktifkan layanan Maps Grounding Lite dan mendapatkan kunci API.

Python

Langkah 1: Menentukan Agen Anda dengan McpToolset untuk Google Maps Grounding Lite

Ubah file agent.py Anda. Ganti YOUR_GOOGLE_MAPS_API_KEY dengan kunci API Anda yang sebenarnya.

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

Langkah 2: Memastikan __init__.py Ada

Pastikan Anda memiliki __init__.py di direktori yang sama dengan agent.py:

from . import agent
    

Langkah 3: Menjalankan adk web dan Berinteraksi

1. Menetapkan Variabel Lingkungan:
   Tetapkan kunci Google Maps API Anda sebagai variabel lingkungan di terminal Anda:

   export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
           

2. Menjalankan adk web:
   Jalankan perintah berikut untuk memulai antarmuka web ADK:

   adk web
           

3. Berinteraksi di UI:
   • Pilih travel_planner_agent.
   • Coba perintah seperti:
     • "I will be in San Francisco tomorrow. What’s the weather like?"
     • "Find coffee shops near Golden Gate Park."
     • "Get directions from GooglePlex to SFO."

Java

Tentukan agen yang menginisialisasi McpToolset di Java. Ganti YOUR_GOOGLE_MAPS_API_KEY_HERE dengan kunci API sebenarnya Anda dapatkan jika tidak menggunakan variabel lingkungan.

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

Tentukan agen yang menginisialisasi MCPToolset di 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"
            }
        })
    ],
});
    

Membagikan masukan

Untuk membagikan masukan tentang Maps Grounding Lite, gunakan formulir berikut:

• Laporkan bug
• Kirim permintaan fitur
• Berikan masukan