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 搭配使用，以便在地图上显示地点。
• 查询天气：请求获取天气信息，并返回当前天气状况、逐小时预报和每日预报。

• 计算路线：请求获取两个地点之间的驾车或步行路线信息，并返回路线距离和时长信息。

  注意： Maps Grounding Lite 不提供逐步路线、路线、实时路况或导航信息。

• 解析名称和解析 Google 地图网址：将地点名称、地址和 Google 地图网址解析为地点 ID。如需了解详情，请参阅 Resolution API。

启用 Maps Grounding Lite MCP 服务器后，LLM 可以调用该服务器公开的新工具，为上述数据类型返回额外的接地信息。虽然 LLM 可以将这些额外信息用作上下文，但 LLM 最终生成的回答可能不包含 MCP 服务器返回的确切信息。您应验证生成的回答是否准确。

Resolution API

Maps Grounding Lite 提供 Resolution API，可让您将自由格式的位置文本和网址解析为结构化 Google 地图地点标识符。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 文本搜索基本功能版（仅 ID） SKU 免费结算。

Maps Grounding Lite 还通过 Essentials 和 Pro 订阅即享优惠套餐提供。

配额

以下配额适用于 Maps Grounding Lite 提供的工具和 API：

• 搜索地点：每个项目每分钟 300 次查询。
• 查询天气：每个项目每分钟 300 次查询。
• 计算路线：每个项目每分钟 300 次查询。
• 解析名称：每个项目每分钟 600 个查询。
• 解析地图网址：每个项目每分钟 600 次查询。

每个 Resolution API 请求都算作一个查询，无论其中包含多少项。

政策和服务条款

Maps Grounding Lite 须遵守 Google Maps Platform 服务条款，包括此服务的服务专用条款。本部分介绍了 Maps Grounding Lite 的其他服务使用要求，包括兼容的 LLM 和来源归因要求。

对兼容 LLM 的要求

您只能将 Maps Grounding Lite 与符合《Google Maps Platform 服务条款》的大语言模型搭配使用。

例如，您有责任确保您选择使用的 LLM 不会缓存、存储或使用 Google 地图内容来改进自身。在使用 Maps Grounding Lite 之前，您需要查看要与 Maps Grounding Lite 搭配使用的所有模型的服务条款。您不得将 Maps Grounding Lite 与任何使用输入到模型中的数据进行模型训练或改进的模型搭配使用。您有责任确保您对模型的使用完全符合《Google Maps Platform 服务条款》（包括服务专用条款）中对 Google 地图内容的限制。

Google 地图来源的标明出处要求

Maps Grounding Lite 的每个工具回答都包含来源。在展示使用 Maps Grounding Lite 提供的工具生成的结果时，您必须按照以下要求添加关联的 Google 地图来源：

• Google 地图来源必须紧跟在这些来源支持的生成内容之后。此类生成的内容也称为接地输出。
• Google 地图来源必须在一次用户互动中可见。

“搜索地点”工具的信息来源

search_places 工具 places 字段提供支持 summary 的来源。对于 places，系统会返回以下元数据：

• place（资源名称）
• id
• location
• googleMapsLinks

对于每个地点，您必须生成符合以下要求的链接预览：

• 请按照地图接地精简版文字提供方指南，将每项来源归属至 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 密钥进行身份验证

您可以将现有 API 密钥与 Maps Grounding Lite 搭配使用，也可以创建新密钥，只要您在 Google Cloud 项目和密钥上都启用 Maps Grounding Lite API 服务即可。

注意： 在测试和原型设计阶段，您也可以免费使用 Maps Demo Key，而无需设置结算账号。

如需使用 API 密钥进行身份验证，请执行以下操作：

1. 按照 Google Maps Platform 使用入门中的步骤创建或配置 API 密钥。
2. 使用 X-Goog-Api-Key 标头将密钥传递给 MCP 服务器。您需要在 LLM 的 MCP 工具配置中将其指定为自定义 HTTP 标头。

注意： 创建或配置 API 密钥时，请务必通过应用适当的限制来限制密钥的使用。如需了解详情，请参阅限制 API 密钥。

使用 OAuth 进行身份验证

您可以使用 OAuth 进行身份验证，方法是创建 OAuth 凭证并将其传递给 MCP 主机或 MCP 服务器应用。

如需使用 OAuth 进行身份验证，请执行以下操作：

1. 在 Google Cloud 控制台中，选择要用于 Maps Grounding Lite 的项目。
2. 在 API 和服务菜单中，选择凭证。
3. 在顶部菜单中，依次选择创建凭据 > OAuth 客户端 ID。
4. 如果项目没有配置的权限请求页面，请点击配置权限请求页面，然后按照屏幕上的说明操作。
5. 在指标部分中，点击创建 OAuth 客户端。
6. 在创建 OAuth 客户端 ID 页面上，选择应用类型，然后输入客户端 ID 的名称。
7. 指定与您的应用类型相关的其他详细信息。 例如，如果您要创建 Web 应用，请为浏览器和服务器请求添加授权 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 配置 大语言模型 以访问 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 问问地图相关问题。例如，您可以尝试输入“Recommend me some restaurants in Mountain View”（向我推荐山景城的一些餐厅），这应该会代表您调用 search_places 工具。

注意： 如需了解如何配置 Gemini CLI 扩展程序以使用 OAuth 访问 Maps Grounding Lite，请参阅 MCP on Google Cloud 文档中的 Gemini CLI 部分。

使用智能体开发套件 (ADK) 配置 Grounding Lite

本部分提供了示例，展示了如何使用智能体开发套件 (ADK) 以及 Python、Java 或 TypeScript 配置 Grounding Lite MCP 服务器。

注意： 请确保您已启用 Maps Grounding Lite 服务并获取了 API 密钥。

Python

您可以在 GitHub 上的 adk-samples 代码库中找到此示例的完整实现。

第 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 存在

确保 __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。
   • 尝试使用以下提示：
     • “我明天要去旧金山。天气怎么样？”
     • “查找金门公园附近的咖啡馆。”
     • “Get directions from GooglePlex to SFO.”（查询从 GooglePlex 到旧金山国际机场的路线。）

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 的反馈，请使用以下表单：

• 报告错误
• 提交功能请求
• 提供反馈