Maps Experience 代理工具

Maps Experience 代理工具 (舊稱 Maps Grounding Lite) 是 Google Maps Platform 服務，支援 Model Context Protocol (MCP) 和 REST，可運用 Google 地圖中可靠的地理空間資料，為 AI 應用程式建立基準。其工具可讓 LLM 存取地點、天氣、空氣品質、花粉和路線資料。其他工具會將地點名稱和 Google 地圖網址解析為地點 ID。您可以在任何支援 MCP 伺服器的工具中啟用 MCP 伺服器，試用 Maps Experience 代理工具。您也可以將每項工具視為 REST 方法呼叫。詳情請參閱「使用 REST 呼叫工具」。

Maps Experience 代理工具是一項產品，有兩個 SKU：Essentials 和 Pro。除非使用 Pro 選項，否則每項要求都會依 Essentials 計費。Pro 選項則可沿著路線搜尋地點、提供更詳細的地點資訊、每次搜尋可傳回更多地點、每條路線可設定更多中途停靠點、根據即時路況規劃路線、提供花粉預報和歷來空氣品質。這兩個 SKU 使用相同的工具、MCP 伺服器、REST 方法和憑證。詳情請參閱「Essentials 和 Pro」。

工具

地圖體驗代理工具可讓 LLM 存取下列 Google 地圖功能：

• 搜尋地點：要求地點相關資訊，並取得 AI 生成的摘要。回應也包含摘要中每個地點的地點 ID、經緯度座標和 Google 地圖連結。您可以使用地點 ID 和經緯度座標，搭配其他 Google Maps Platform API，在地圖上顯示地點。如要使用 Places UI Kit 顯示這些地點，且不需額外付費，請使用代理資料視覺化權杖 (預先發布版)。使用 Pro 方案，即可要求更多 Place Details，例如評論洞察資料，每次要求最多可取得 10 個地點。
• 沿路線搜尋： 尋找旅遊路線沿途的地點 (使用 compute_routes、route_endpoints 或 encoded_polyline 的 retrieval_token 指定)，並取得 AI 生成的摘要、地點詳細資料、繞道距離和行程時間，以及代理資料視覺化權杖 (預先發布版)。每項 search_along_route 要求都會依 Pro SKU 計費。
• 查詢天氣：要求提供特定地點的環境狀況，包括天氣 (目前狀況、24 小時內每小時記錄，以及最多 10 天內每小時和每日預報)，以及目前或最多 4 天內的空氣品質預報。使用 Pro 方案，還能要求最多 5 天的每日花粉預測 (含植物物種詳細資料)，以及最多 30 天的每小時空氣品質記錄。

• 計算路線：要求起點和目的地之間的路線 (可選擇是否經過中途停靠點)，並傳回路線的距離、時間長度，以及 DRIVE 路線的 retrievalToken，以便傳遞至 search_along_route。Pro 方案可根據即時路況規劃路線，並加入更多中途停靠點。

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

啟用 MCP 伺服器後，LLM 就能呼叫其工具，取得這些資料類型的基準資訊。LLM 可將這項資訊做為背景資訊。不過，最終回覆可能不含 MCP 伺服器傳回的確切資訊。驗證生成的回覆是否正確。

Essentials 和 Pro

Essentials 和 Pro 是同一產品的兩個 SKU，而非獨立產品或方案。如果要求使用 Pro 選項，則會依 Pro 計費。其他要求則會依 Essentials 計費。Pro 選項是工具要求中的一般欄位，因此 LLM 可以代表您使用這些選項。代理也可以在同一個對話中使用這兩種 SKU。舉例來說，代理可能會使用 Essentials 尋找地標附近的咖啡店。接著，Pro 模型可能會用來回答有關招牌飲品和座位的後續問題。Pro 沒有獨立的 MCP 伺服器、端點或憑證。

比較 Essentials、Pro 和利用 Google 地圖建立基準

利用 Google 地圖建立基準是獨立產品。這項功能已內建於 Gemini API、Google AI Studio 和 Gemini Enterprise Agent Platform 的 Gemini 模型中。模型會決定何時查詢 Google 地圖，並傳回有依據的答案和引用來源。在 Gemini 建構模型時，如果想讓模型處理基準建立作業，請選擇「利用 Google 地圖建立基準」。如要使用其他模型或代理架構，或直接控制各項工具呼叫，請選擇 Maps Experiments 代理工具。

下表比較 Essentials SKU、Pro SKU 和「利用 Google 地圖建立基準」：

無論使用哪種 SKU，下列選項的運作方式都相同：交通工具、出發和抵達時間、替代路線、路線折線、天氣查詢、目前和預測空氣品質查詢 (包括污染物濃度和當地 AQI 量表)、天氣單位系統，以及 Resolution API。不會變更要求計入的 SKU。

Pro SKU 的計費項目

下表摘要說明 Essentials 包含的功能，以及哪些功能需要 Pro SKU：

如要瞭解啟用各項功能的請求選項，請參閱「搜尋地點」、「沿路線搜尋」、「計算路線」和「查詢天氣」。

控管 Pro 使用情形

search_places、compute_routes 和 lookup_weather 預設會關閉專業選項。當使用者的要求需要這些參數，且工具說明或您的指令允許時，LLM 會設定這些參數，或呼叫 search_along_route。工具說明會告知模型哪些選項費用較高，以及何時使用：page_size 高於 5、擴充 Place Details、超過 10 個中繼路線控點、路況感知路線規劃和 search_along_route。如果使用 REST 呼叫工具，程式碼會設定每個選項。如何管理費用：

• 告訴模型何時適合使用 Pro 選項。例如：「只有在使用者詢問評論、菜單或氣氛時，才將 include_extended_details 設為 True。」或「只有在使用者要求目前行程時間時，才使用 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL」。或「只有在使用者要求沿途地點時，才呼叫 search_along_route」。或：「只有在使用者詢問花粉、過敏或過往空氣品質時，才加入 POLLEN 或 AIR_QUALITY，並附上過往的 date 或 hour。」
• 如要讓代理維持在 Essentials SKU，請指示模型不要呼叫 search_along_route 或使用 Pro 選項。Pro 選項包括 include_extended_details、page_size 超過 5、ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL、超過 10 個中途路線控點、capabilities 中的 POLLEN，以及 capabilities 中 AIR_QUALITY 的過去 date 或 hour。如果 MCP 用戶端可以限制工具或工具引數，您也可以在工具設定中封鎖 search_along_route 和這些引數值。
• 在帳單報表中監控 Maps Grounding Pro SKU，並設定預算快訊。

Resolution API

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

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

傳回的地點 ID 可用於其他 Google 地圖平台 API。每則回覆也包含一個連結，可將解析的地點儲存為 Google 地圖中的清單。

詳情請參閱 Maps Tools Resolution API。

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

計費和配額

計費方式

Google Maps Platform 採用即付即用定價模式，地圖體驗代理工具的用量是按要求計算。每個要求代表一個計費事件。系統會追蹤每個產品 SKU 的用量。帳單會顯示每個 SKU 的明細項目和總費用。詳情請參閱「報表總覽」。

透過 MCP 伺服器或 REST 提出的每個「Place Search」、「沿路線搜尋」、「計算路線」或「查詢天氣」要求，都會依據一個 SKU 計費：Maps Grounding Essentials 或 Maps Grounding Pro。每個 search_along_route 要求和使用 Pro 選項的要求，都會依 Pro SKU 計費。系統不會同時依據這兩個 SKU 向您收取要求費用，且要求中的 Pro 選項數量不會影響費用。如要瞭解決定各項工具 SKU 的功能和選項，請參閱「Pro SKU 的計費項目」。

Maps Grounding Essentials 要求：每月前 10,000 次要求免費，之後每 1,000 次要求 $7.00 美元。Maps Grounding Pro 要求：每月前 5,000 次要求免費，之後每 1,000 次要求 $14.00 美元。這兩個 SKU 都提供高用量折扣，每月用量越高，折扣越多。

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

解析 API 要求 (ResolveNames 和 ResolveMapsUrls) 屬於 Places API Text Search Essentials (IDs Only) SKU，不收取費用。

如果您使用 Places UI Kit 顯示 search_places 或 search_along_route 回應中的地點，可以使用代理資料視覺化權杖 (預先發布版)，這樣系統就不會對這些 Places UI Kit 要求收費。

Essentials 和 Pro Subscribe to save 方案包含 Essentials SKU 的用量。Pro 方案包含 Pro SKU 的用量。

配額

下列配額適用於 Maps Experiments 代理工具提供的工具和 API：

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

配額會依工具計算，並由 Essentials 和 Pro SKU 共用。Pro 要求與 Essentials 要求對相同工具的配額消耗量相同。

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

政策和服務條款

Maps Experiments 代理工具受《Google Maps Platform 服務條款》規範，包括服務專屬條款。本節說明 Maps Experience 代理工具的其他使用規定，包括相容的 LLM 和來源歸因。無論要求是以哪個 SKU 計費，所有結果都必須符合這些規定。

相容 LLM 的規定

Maps Experience 代理工具只能搭配符合《Google 地圖平台服務條款》的大型語言模型使用。

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

Google 地圖來源的出處標示規定

Maps Experiments 代理工具的每項工具回覆都會包含來源。呈現地圖體驗代理工具的結果時，必須附上相關 Google 地圖來源，並符合下列規定：

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

「搜尋地點」和「搜尋沿途地點」工具的來源

search_places 工具 places 欄位和 search_along_route 工具 results[].place 欄位會提供支援 summary 的來源。每個地點都會傳回下列中繼資料：

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

針對每個地點，您必須產生符合下列規定的連結預覽：

• 請按照地圖體驗代理工具文字出處指南，將每個來源歸功於 Google 地圖。
• 使用回應中的 googleMapsLinks.placeUrl 連結至來源。

如果摘要包含 Pro 提供的詳細地點資訊 (例如評論洞察)，也必須遵守這些規定。summary 會使用從零開始的索引 (例如 [0]) 引用每個地點，並對應至 places 或 results 中的項目。每個地點也包含 googleMapsLinks.reviewsUrl，可連結至 Google 地圖上的地點評論。使用者可以點選連結，查看洞察背後的評論。

語音優先介面

如果應用程式透過語音呈現地圖體驗代理工具結果，也必須符合語音優先介面的需求。摘要說明：

• 來源：在隨播 UI 中顯示 Google 地圖來源，並逐字記錄語音對話。
• 主動揭露：在互動時，告知使用者 AI 生成內容可能包含 Google 地圖的資訊。並說明可在隨附的使用者介面中查看詳細來源。你可以透過螢幕或語音執行這項操作。
• 持續揭露：持續提供說明，例如在語音設定選單中，說明 AI 生成內容可能包含 Google 地圖內容。
• 使用者查詢：準確回答使用者關於內容來源的問題，並引導他們前往隨附 UI 查看詳細資料。

設定 LLM 使用 MCP 伺服器

如要使用地圖體驗代理工具，您必須擁有 Google Cloud 雲端專案，並啟用 Maps Experience agent tools API 服務。此外，您也需要 API 金鑰或 OAuth 用戶端 ID。接著，您可以設定 LLM 存取 MCP 伺服器。MCP 伺服器會使用 Streamable HTTP 傳輸。

在 Google Cloud 專案啟用地圖體驗代理工具

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

1. 在 Google Cloud 控制台中，選擇要用於 Maps Experience 代理工具的專案。
2. 在 Google Cloud 控制台中啟用專案的計費功能。
3. 在 Google Cloud 控制台 API 程式庫中啟用 Maps Experience 代理工具。

使用 API 金鑰進行驗證

您可以使用現有的 API 金鑰，也可以建立新的金鑰，搭配地圖體驗代理工具。無論採用哪種方式，請在 Google Cloud 雲端專案和金鑰上啟用 Maps Experience 代理工具 API 服務。

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

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

使用 OAuth 驗證

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

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

1. 在 Google Cloud 控制台中，選擇要用於 Maps Experience 代理工具的專案。
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 伺服器應用程式時，請傳遞 OAuth 用戶端 ID 和密鑰。您也必須要求下列範圍：https://www.googleapis.com/auth/maps-platform.mapstools。

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

設定 LLM 存取地圖體驗代理工具 MCP 伺服器

啟用 Maps Experience 代理工具服務並建立憑證後，即可設定 LLM 存取 MCP 伺服器。請按照 LLM 的 MCP 設定說明文件操作，並使用 MCP 伺服器網址：https://mapstools.googleapis.com/mcp

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

使用 Gemini CLI 設定地圖體驗代理工具

本節提供範例，說明如何使用 Gemini CLI 設定 Maps Experience 代理工具 MCP 伺服器。詳情請參閱「搭配使用 MCP 伺服器與 Gemini CLI」。

1. 安裝 Gemini CLI 後，請執行 gemini mcp add 來設定 MCP 伺服器：

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

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

2. 執行 /mcp list 指令，驗證伺服器是否正常運作：

   > /mcp list
   
   Configured MCP servers:
   
   maps-experience-agent-tools-mcp - Ready (6 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_along_route
   -   search_places
   

3. 開始使用 CLI 詢問 Google 地圖相關問題。例如，您可以嘗試「推薦一些 Mountain View 的餐廳」，系統會代表您呼叫 search_places 工具。

使用 Agent Development Kit (ADK) 設定 Maps Experiments 代理工具

本節說明如何使用 Python、Java 或 TypeScript 的 Agent Development Kit (ADK) 設定 MCP 伺服器。

# ./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: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});
    

使用 REST 呼叫工具

地圖體驗代理工具中的每項工具，也都能以 REST 方法的形式使用。如要將工具連結至自己的代理或應用程式，請直接呼叫 REST 方法，例如為模型宣告自己的函式、選擇模型可設定的選項，或在程式碼中設定預設值。

下表列出各項工具的 REST 方法：

REST 要求會採用與對應工具相同的選項，並傳回相同的回應。在 REST 要求和回應主體中，欄位名稱會使用小駝峰式大小寫，例如 textQuery 而非 text_query。REST 要求會依據相同的 SKU 計費、遵循 Pro 選項的相同規則，並計入與 MCP 工具呼叫相同的配額。

如要驗證，請使用與 MCP 伺服器相同的 Google Cloud 專案和憑證。如需設定步驟，請參閱「設定 LLM 使用 MCP 伺服器」。在 X-Goog-Api-Key 標頭中傳遞 API 金鑰，或在 Authorization 標頭中傳遞具有 https://www.googleapis.com/auth/maps-platform.mapstools 範圍的 OAuth 存取權杖。

以下範例會呼叫 searchText 方法：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

將 API_KEY 替換為您的 API 金鑰。

回應包含與 search_places 工具結果相同的 summary、places 和 contentToken 欄位。每項工具的指南都會顯示範例的 REST 版本。

提供意見

如要針對地圖體驗代理工具提供意見，請使用下列任一表單：

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