Maps Grounding Lite

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

工具

Maps Grounding Lite 提供工具，讓 LLM 存取下列 Google 地圖功能：

• 搜尋地點： 要求地點相關資訊，並取得 AI 生成的地點資料摘要，以及摘要中各地點的地點 ID、經緯度座標和 Google 地圖連結。您可以將傳回的地點 ID 和經緯度座標與其他 Google 地圖平台 API 搭配使用，在地圖上顯示地點。
• 查詢天氣： 要求提供天氣資訊，並傳回目前狀況、每小時預報和每日預報。

• 計算路線： 要求兩個地點之間的行車或步行路線資訊，並傳回路線距離和時間長度資訊。

  注意： Maps Grounding Lite 不提供逐步路線、轉送、即時路況或導航資訊。

啟用 Maps Grounding Lite MCP 伺服器後，LLM 就能呼叫伺服器公開的新工具，傳回上述資料類型的其他基礎資訊。雖然 LLM 可以使用這項額外資訊做為脈絡，但 LLM 最終生成的回覆可能不會包含 MCP 伺服器傳回的確切資訊。請務必驗證生成的回覆內容是否準確。

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

帳單與配額

計費方式

Google 地圖平台採用「即付即用」定價模式，系統會針對每項要求計算 Grounding Lite 的用量，每項要求代表一個計費事件。系統會追蹤每個產品 SKU 的用量。帳單會列出每個 SKU 的明細項目，以及總費用。詳情請參閱「報表總覽」。

如需詳細價格資訊，請參閱主要價目表和印度價目表。

您也可以透過 Essentials 和 Pro 訂閱方案取得 Maps Grounding Lite。

配額

地圖 Grounding Lite 提供的工具適用下列配額規定：

• 搜尋地點：每項專案每分鐘 300 個查詢。
• 查詢天氣：每項專案每分鐘 300 次查詢。
• 計算路徑：每項專案每分鐘 300 個查詢。

政策和服務條款

Maps Grounding Lite 須遵守《Google Maps Platform 服務條款》，包括這項服務的服務專屬條款。本節說明 Maps Grounding Lite 的額外服務使用規定，包括相容的 LLM 和來源出處規定。

相容 LLM 的需求條件

您只能搭配符合《Google 地圖平台服務條款》的 LLM 使用 Maps Grounding Lite。

舉例來說，您有責任確保 Google 地圖內容不會由您選擇使用的 LLM 進行快取、儲存或用於改善 LLM。使用 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

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

• 請按照 Maps Grounding Lite 文字出處標註規範，將每個來源標註為 Google 地圖。
• 使用回應中的 places.googleMapsLinks.placeUrl 連結至來源。

設定 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 金鑰進行驗證

只要在 Google Cloud 雲端專案和金鑰上啟用 Maps Grounding Lite API 服務，您就能搭配使用現有 API 金鑰或建立新的金鑰。

注意： 如要進行測試和原型設計，您也可以使用Maps 試用金鑰，無須設定帳單帳戶，即可免費使用。

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

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

注意： 建立或設定 API 金鑰時，請務必套用適當的限制，以限制金鑰的使用。詳情請參閱「限制 API 金鑰」一文。

使用 OAuth 進行驗證

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

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

1. 在 Google Cloud 控制台中，選擇要用於 Maps Grounding Lite 的專案。
2. 在「API 和服務」選單中，選取「憑證」。
3. 在頂端選單中，選取「建立憑證」>「OAuth 用戶端 ID」。
4. 如果專案未設定同意畫面，請按一下「設定同意畫面」，然後按照畫面上的指示操作。
5. 在「指標」部分，按一下「建立 OAuth 用戶端」。
6. 在「建立 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 伺服器

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

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

使用 Gemini CLI 設定 Maps Grounding Lite

本節提供範例，說明如何使用 Gemini CLI 設定 Maps Grounding Lite MCP 伺服器。詳情請參閱「使用 Gemini CLI 的 MCP 伺服器」。

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 (3 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   search_places
   

3. 開始透過 CLI 詢問地圖相關問題。舉例來說，試著說出「推薦幾間 Mountain View 的餐廳」，這應該會代表你呼叫 search_places 工具。

注意： 如要瞭解如何設定 Gemini CLI 擴充功能，透過 OAuth 存取 Maps Grounding Lite，請參閱 Google Cloud 說明文件中的 MCP Gemini CLI 專節。

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

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

注意： 請務必啟用 Maps Grounding Lite 服務並取得 API 金鑰。

Python

步驟 1：使用 McpToolset 定義代理，以建立 Google 地圖 Grounding Lite 基準

修改 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 是否存在

確認您在與 agent.py 相同的目錄中擁有 __init__.py：

from . import agent
    

步驟 3：執行 adk web 並互動

1. 設定環境變數：
   在終端機中將 Google Maps API 金鑰設為環境變數：

   export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
           

2. 執行 adk web：
   執行下列指令，啟動 ADK 網頁介面：

   adk web
           

3. 在使用者介面中互動：
   • 選取travel_planner_agent。
   • 你可以嘗試以下提示：
     • 「我明天會在舊金山。天氣如何？」
     • 「Find coffee shops near Golden Gate Park」(尋找金門公園附近的咖啡廳)。
     • 「取得從 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 的意見，請填寫下列表單：

• 回報錯誤
• 提交功能要求
• 提供意見