Maps Grounding Lite

Google Maps Platform Grounding Lite 是一項支援 Model Context Protocol (MCP) 的服務,可讓您輕鬆運用 Google 地圖中可靠的地理空間資料,為 AI 應用程式建立基準。MCP 伺服器提供的工具可讓 LLM 存取地點、天氣和路線功能,並將地點名稱和 Google 地圖網址解析為地點 ID。您可以在任何支援 MCP 伺服器的工具中啟用 Maps Grounding Lite,試用這項功能。

工具

Maps Grounding Lite 提供工具,可讓 LLM 存取下列 Google 地圖功能:

  • 搜尋地點:要求地點資訊,並取得 AI 生成的地點資料摘要,以及摘要中每個地點的地點 ID、經緯度座標和 Google 地圖連結。您可以使用傳回的地點 ID 和經緯度座標,搭配其他 Google Maps Platform API,在地圖上顯示地點。
  • 查詢天氣:要求天氣資訊,並傳回目前天氣狀況、每小時預報和每日預報。
  • 計算路線:要求兩個地點之間的行車或步行路線資訊,並傳回路線距離和時間長度資訊。

  • 解析名稱和解析地圖網址:將地點名稱、地址和 Google 地圖網址解析為地點 ID。詳情請參閱 Resolution API。

啟用 Maps Grounding Lite MCP 伺服器後,LLM 就能呼叫伺服器公開的新工具,為上述資料類型傳回額外的基準資訊。雖然 LLM 可以使用這項額外資訊做為背景資訊,但最終生成的回覆不一定會包含 MCP 伺服器傳回的確切資訊。請務必檢查生成的回覆是否準確。

Resolution API

Maps Grounding Lite 提供 Resolution API,可將任意形式的位置文字和網址,解析為結構化的 Google 地圖地點 ID。Resolution API 可透過 REST 方法和 Maps Grounding Lite MCP 伺服器上的工具使用:

  • 解析名稱 (REST、MCP):將一批地點名稱或地址解析為 Google 地圖上的特定地點實體。這項功能可將非結構化使用者查詢,轉換為穩定的地點 ID。
  • 解析地圖網址 (REST、MCP):解析一批 Google 地圖網址,找出特定地點實體。支援的格式包括標準地點網址和短網址。

傳回的地點 ID 可與其他 Google Maps Platform API 搭配使用。每則回覆也包含一個連結,可將解析的地點儲存為 Google 地圖中的清單。

詳情請參閱 Maps Tools Resolution API。

試用 Maps Grounding Lite 範例應用程式 (在新分頁中開啟)

計費和配額

計費方式

Google Maps Platform 採用即付即用定價模式,Maps Grounding Lite 的用量是按要求計算,每項要求代表一個計費事件。系統會追蹤每個產品 SKU 的用量。帳單除了顯示總費用,也會逐項列出每個 SKU。詳情請參閱報表總覽。

如需定價詳情,請參閱主要價目表和印度價目表。

向 Resolution API (ResolveNames 和 ResolveMapsUrls) 提出的要求,會以 Places API Text Search Essentials (IDs Only) SKU 計費,不收取費用。

Maps Grounding Lite 也包含在 Essentials 和 Pro 的訂閱優惠方案中。

配額

下列配額適用於 Maps Grounding Lite 提供的工具和 API:

  • 搜尋地點:每項專案每分鐘 300 次查詢。
  • 查詢天氣:每項專案每分鐘 300 次查詢。
  • Compute routes:每項專案每分鐘 300 次查詢。
  • 解析名稱:每項專案每分鐘 600 次查詢。
  • 解析 Maps 網址:每項專案每分鐘 600 次查詢。

無論包含多少項目,每項 Resolution API 要求都算是一次查詢。

政策和服務條款

Maps Grounding Lite 受到《Google Maps Platform 服務條款》規範,包括本服務的服務專屬條款。本節說明 Maps Grounding Lite 的其他服務使用規定,包括相容的 LLM 和來源歸因規定。

相容 LLM 的規定

Maps Grounding Lite 只能與符合《Google 地圖平台服務條款》的大型語言模型搭配使用。

舉例來說,您有責任確保 Google 地圖內容不會遭到快取、儲存,或用於改善您選擇使用的 LLM。使用 Maps Grounding Lite 前,請務必詳閱要搭配 Maps Grounding Lite 使用的模型《服務條款》。請勿將 Maps Grounding Lite 與任何會使用輸入資料訓練或改良的模型搭配使用。您有責任確保使用模型時,完全遵守《Google 地圖平台服務條款》中 Google 地圖內容的限制,包括服務專屬條款。

Google 地圖來源的作者資訊相關規定

Maps Grounding Lite 的每項工具回覆都會包含來源。呈現使用 Maps Grounding Lite 提供的工具所得出的結果時,您必須加入相關的 Google 地圖來源,並符合下列規定:

  • Google 地圖來源必須緊接在來源支援的生成內容之後。這類生成內容也稱為基準輸出。
  • Google 地圖來源必須在一次使用者互動中可供查看。

「搜尋地點」工具的來源

search_places 工具 places 欄位會提供支援 summary 的來源。如果是 places,系統會傳回下列中繼資料:

  • place (資源名稱)
  • id
  • location
  • googleMapsLinks

每個地點都必須產生符合下列規定的連結預覽:

設定 LLM 使用 MCP 伺服器

如要使用 Maps Grounding Lite,您必須先建立 Google Cloud 雲端專案,並啟用 Maps Grounding Lite API 服務,以及 API 金鑰或 OAuth 用戶端 ID。接著,您可以設定 LLM 存取 MCP 伺服器。Grounding Lite MCP 伺服器使用串流 HTTP 傳輸。

在 Google Cloud 雲端專案啟用 Maps Grounding Lite 服務

如要在專案中啟用 API,請按照下列步驟操作:

  1. 在 Google Cloud 控制台中,選擇要用於 Maps Grounding Lite 的專案。
  2. 在 Google Cloud 控制台中啟用專案的計費功能。
  3. 在 Google Cloud 控制台 API 程式庫中啟用 Maps Grounding Lite。

使用 API 金鑰進行驗證

您可以使用現有的 API 金鑰搭配 Maps Grounding Lite,也可以建立新的金鑰,只要在 Google Cloud 雲端專案和金鑰上啟用 Maps Grounding Lite API 服務即可。

如要使用 API 金鑰進行驗證,請按照下列步驟操作:

  1. 按照「開始使用 Google 地圖平台」中的步驟,建立或設定 API 金鑰。
  2. 使用 X-Goog-Api-Key 標頭將金鑰傳遞至 MCP 伺服器。您必須在 LLM 的 MCP 工具設定中,將這項資訊指定為自訂 HTTP 標頭。

使用 OAuth 驗證

您可以建立 OAuth 憑證,並將憑證傳遞至 MCP 主機或 MCP 伺服器應用程式,使用 OAuth 進行驗證。

如要使用 OAuth 進行驗證,請按照下列步驟操作:

  1. 在 Google Cloud 控制台中,選擇要用於 Maps Grounding Lite 的專案。
  2. 在「API 和服務」選單中,選取「憑證」。
  3. 在頂端選單中,依序選取「Create credentials」(建立憑證) >「OAuth client ID」(OAuth 用戶端 ID)。
  4. 如果專案未設定同意畫面,請按一下「Configure consent screen」(設定同意畫面),然後按照畫面上的指示操作。
  5. 在「指標」部分,按一下「建立 OAuth 用戶端」。
  6. 在「Create OAuth client ID」(建立 OAuth 用戶端 ID) 畫面中,選取應用程式類型,然後輸入用戶端 ID 的名稱。
  7. 根據申請類型,提供其他相關詳細資料。 舉例來說,如果您要建立網頁應用程式,請為瀏覽器和伺服器要求新增授權 URI。
  8. 建立用戶端後,請儲存用戶端 ID 和密鑰。
  9. 設定 MCP 主機或 MCP 伺服器應用程式存取 Maps Grounding Lite 時,請傳遞 OAuth 用戶端 ID 和密鑰。您也必須要求下列範圍:https://www.googleapis.com/auth/maps-platform.mapstools。

詳情請參閱「使用 OAuth 2.0 存取 Google API」。

設定 LLM 存取 Maps Grounding Lite MCP 伺服器

建立 Google Cloud 雲端專案並啟用 Maps Grounding Lite API 服務,並取得有效憑證 (例如 API 金鑰或 OAuth 用戶端 ID 和 Secret) 後,即可按照對應的 MCP 設定說明文件,並使用 Maps Grounding Lite MCP 伺服器網址:https://mapstools.googleapis.com/mcp,設定 LLM 存取 MCP 伺服器。

詳情請參閱「在 AI 應用程式中設定 MCP」。

使用 Gemini CLI 設定 Maps Grounding Lite

本節說明如何使用 Gemini CLI 設定 Maps Grounding Lite MCP 伺服器。詳情請參閱「搭配使用 MCP 伺服器與 Gemini CLI」。

  1. 安裝 Gemini CLI 後,您可以使用 add 指令設定 Maps Grounding Lite MCP 伺服器:

    gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
    

    如果設定成功,您應該會看到確認訊息,指出伺服器已新增至使用者設定。

  2. 如要驗證伺服器是否正常運作,請執行 /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. 開始使用 CLI 詢問 Google 地圖相關問題。舉例來說,您可以試著輸入「推薦一些山景城的餐廳」,系統應該會代表您呼叫 search_places 工具。

使用 Agent Development Kit (ADK) 設定 Grounding Lite

本節提供範例,說明如何使用 Agent Development Kit (ADK) 和 Python、Java 或 TypeScript 設定 Grounding Lite MCP 伺服器。

Python

如需本範例的完整實作,請前往 GitHub 的 adk-samples 存放區。

步驟 1:使用 Google 地圖 Grounding Lite 的 McpToolset 定義代理

修改 agent.py 檔案。將 YOUR_GOOGLE_MAPS_API_KEY 替換成實際的 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"
                }
            )
        )
    ]
)
    
步驟 2:確認 __init__.py 存在

確認 __init__.py 與 agent.py 位於同一目錄:

from . import agent
    
步驟 3:執行 adk web 並互動
  1. 設定環境變數:
    在終端機中,將 Google 地圖 API 金鑰設為環境變數:
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
            
  2. 執行 adk web:
    執行下列指令,啟動 ADK 網頁介面:
    adk web
            
  3. 在使用者介面中互動:
    • 選取「travel_planner_agent」。
    • 試試下列提示詞:
      • 「我明天會去舊金山。天氣如何?」
      • 「尋找金門公園附近的咖啡廳。」
      • 「取得從 GooglePlex 到 SFO 的路線。」

Java

定義在 Java 中初始化 McpToolset 的代理。如果您不使用環境變數,請將 YOUR_GOOGLE_MAPS_API_KEY_HERE 替換為您取得的實際 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

定義在 TypeScript 中初始化 MCPToolset 的代理:

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

提供意見

如要提供 Maps Grounding Lite 相關意見,請使用下列表單: