Maps Grounding Lite

Google Maps Platform Grounding Lite adalah layanan dengan dukungan Model Context Protocol (MCP) yang memudahkan grounding aplikasi AI Anda dengan data geospasial tepercaya dari Google Maps. Server MCP menyediakan alat yang memungkinkan LLM mengakses kemampuan untuk tempat, cuaca, dan rute, serta me-resolve nama lokasi dan URL Google Maps ke ID Tempat. 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:

• Telusuri tempat: Minta informasi tentang tempat dan dapatkan ringkasan data tempat yang dihasilkan AI, serta ID Tempat, koordinat lintang dan bujur, serta link Google Maps untuk setiap tempat yang disertakan dalam ringkasan. Anda dapat menggunakan ID Tempat serta koordinat lintang dan 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 cuaca per jam, dan prakiraan cuaca harian.

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

• Selesaikan nama dan Selesaikan URL Maps: Selesaikan nama lokasi, alamat, dan URL Google Maps ke ID Tempat. Untuk informasi selengkapnya, lihat Resolution API.

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.

Resolution API

Maps Grounding Lite menyediakan Resolution API, yang memungkinkan Anda me-resolve teks lokasi dan URL bentuk bebas ke ID tempat Google Maps terstruktur. Resolution API tersedia sebagai metode REST dan sebagai alat di server MCP Maps Grounding Lite:

• Menyelesaikan nama (REST, MCP): Menyelesaikan sekumpulan nama atau alamat lokasi ke entity tempat tertentu di Google Maps. Hal ini berguna untuk melakukan grounding kueri pengguna yang tidak terstruktur ke ID Tempat yang stabil.
• Resolve Maps URLs (REST, MCP): Menyelesaikan sekumpulan URL Google Maps ke entitas tempat tertentu. Format yang didukung mencakup URL tempat standar dan URL yang dipersingkat.

Anda dapat menggunakan ID Tempat yang ditampilkan dengan Google Maps Platform API lainnya. Setiap respons juga menyertakan link yang menyimpan tempat yang di-resolve sebagai daftar di Google Maps.

Untuk mengetahui informasi selengkapnya, lihat Maps Tools Resolution API.

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

Penagihan dan kuota

Cara Anda ditagih

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 SKU produk. Tagihan Anda menampilkan item baris untuk setiap SKU selain total tagihan Anda. Lihat Ringkasan pelaporan untuk mengetahui informasi selengkapnya.

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

Permintaan ke Resolution API (ResolveNames dan ResolveMapsUrls) ditagih tanpa biaya berdasarkan SKU Places API Text Search Essentials (IDs Only).

Maps Grounding Lite juga ditawarkan melalui paket Berlangganan untuk menghemat Essentials dan Pro.

Kuota

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

• Search places: 300 kueri per menit, per project.
• Pencarian cuaca: 300 kueri per menit, per project.
• Compute routes: 300 kueri per menit, per project.
• Menyelesaikan nama: 600 kueri per menit, per project.
• Menyelesaikan URL Maps: 600 kueri per menit, per project.

Setiap permintaan Resolution API dihitung sebagai satu kueri, terlepas dari jumlah item yang dimuatnya.

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 boleh 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 kualitas model apa pun. Anda bertanggung jawab untuk memastikan bahwa penggunaan model oleh Anda sepenuhnya mematuhi batasan terkait 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 tersebut. Konten yang dihasilkan ini juga disebut sebagai Output Grounding.
• Sumber Google Maps harus dapat dilihat dalam satu interaksi pengguna.

Sumber untuk alat Telusuri tempat

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

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

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

• Atribusikan setiap sumber ke Google Maps, dengan mengikuti panduan atribusi teks 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.

Aktifkan layanan Maps Grounding Lite di project Google Cloud Anda

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 Konsol Google Cloud.
3. Aktifkan Maps Grounding Lite di Library API Konsol Google Cloud.

Melakukan autentikasi menggunakan kunci API

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

Untuk melakukan autentikasi menggunakan kunci API:

1. Buat atau konfigurasikan kunci API dengan mengikuti langkah-langkah di Memulai 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.

Melakukan autentikasi menggunakan OAuth

Anda dapat melakukan autentikasi menggunakan OAuth dengan membuat kredensial OAuth dan meneruskannya ke aplikasi host MCP atau 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 & Services, pilih Credentials.
3. Di menu atas, pilih Create credentials > OAuth client ID.
4. Jika project tidak memiliki layar izin yang dikonfigurasi, klik Configure consent screen dan ikuti petunjuk di layar.
5. Di bagian Metrik, klik Buat klien OAuth.
6. Di layar Create OAuth client ID, pilih jenis aplikasi dan masukkan nama untuk client ID.
7. Tentukan detail tambahan yang relevan dengan jenis permohonan Anda. Misalnya, jika Anda membuat aplikasi web, tambahkan URI yang diizinkan untuk permintaan browser dan server.
8. Setelah klien Anda dibuat, simpan client ID dan rahasia klien.
9. Saat mengonfigurasi aplikasi host MCP atau server MCP Anda untuk mengakses Maps Grounding Lite, teruskan client ID dan rahasia 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 Anda memiliki project Google Cloud dengan layanan Maps Grounding Lite API yang diaktifkan dan kredensial yang valid, seperti kunci API atau client ID dan rahasia 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 Grounding Maps 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 Anda.

2. Untuk memvalidasi bahwa server berfungsi dengan benar, jalankan perintah /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
   

3. Mulai ajukan pertanyaan terkait Maps dengan CLI. Misalnya, coba "Rekomendasikan beberapa restoran di Mountain View" yang akan memanggil alat search_places atas nama Anda.

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.

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

Membagikan masukan

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

• Laporkan bug
• Mengirim permintaan fitur
• Berikan masukan