升级到 Pro SKU，即可使用更多地图实验专区智能体工具功能！了解 Pro

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Maps Tools Resolution API

Maps Tools Resolution API 是地图体验智能体工具（以前称为 Maps Grounding Lite）的一部分。它提供批量端点，可将地点名称和 Google 地图网址解析为 Google 地图地点 ID。您可以将返回的地点 ID 与其他 Google Maps Platform API 搭配使用。每个回答还包含一个链接，用于将解析出的地点保存为 Google 地图中的列表。

Resolution API 既可以作为 REST 方法使用，也可以作为地图体验智能体工具 MCP 服务器上的工具使用：

能力	REST 方法	MCP 工具
将位置名称或地址解析为地点	`resolveNames`	`resolve_names`
将 Google 地图网址解析为地点	`resolveMapsUrls`	`resolve_maps_urls`

准备工作

如需使用 Resolution API，您需要一个已启用结算功能且已启用地图体验代理工具 API 服务的 Google Cloud 项目。如需查看相关说明，请参阅在 Google Cloud 项目中启用地图体验智能体工具。

API 访问权限和身份验证

Resolution API 同时支持 API 密钥和 OAuth 2.0 凭证。

API 密钥

您可以通过在 X-Goog-Api-Key 标头中传递有效的 Google Maps Platform API 密钥或将其附加到请求网址来对请求进行身份验证：

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

在本页面的示例中，请将 API_KEY 替换为您的 API 密钥。

OAuth 2.0 范围

如果您使用 OAuth 授权，则支持以下范围：

https://www.googleapis.com/auth/maps-platform.mapstools

用量限额

以下默认配额适用于 Resolution API：

ResolveNames：每个项目每分钟 600 次查询。
ResolveMapsUrls：每个项目每分钟 600 次查询。
批次大小：每个请求中最多包含 20 个查询或网址。

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

价格

根据 Places API 文本搜索基本功能版（仅 ID） SKU，对 ResolveNames 和 ResolveMapsUrls 的请求不收取任何费用（0 美元）。与地图体验智能体工具的其他部分一样，您的项目必须有结算账号。

请求验证和限制

为防止负载过高并确保快速响应，系统会根据以下规则验证批量请求：

批处理大小限制：这两种方法都允许在每个请求中最多包含 20 项。
ResolveNames 要求：
- queries 中的每个项都必须指定一个非空 text 参数。
- 查询必须代表特定的地点名称或地址，例如 "Googleplex, Mountain View, CA" 或 "Eiffel Tower, Paris"。
- 不支持一般类别搜索（例如 "restaurants in New York"）或不含位置信息的通用连锁店名称（例如 "Starbucks"），并且可能无法解析。
ResolveMapsUrls 要求：
- 每个网址都必须是结构有效的 Google 地图网址。
- 支持的格式包括：
  - 标准地点网址：https://www.google.com/maps/place/...
  - 缩短的网址：https://maps.app.goo.gl/...
- 不支持基于宽泛查询的 Google 地图网址（例如 https://maps.google.com/?q=restaurant）以及未指向单个唯一地点的网址。

将解析出的地点保存到 Google 地图

如果批处理中至少有一项解析成功，则响应中会包含 saveToMapsUrl 字段。这是一个 Google 地图链接，其中包含批处理中所有成功解析的地点。向希望在 Google 地图中将解析后的地点保存、分享或打开为列表的用户显示此链接。

请始终使用 API 返回的链接。请勿自行构建链接。如果批处理中没有项解析，则响应不包含 saveToMapsUrl。

处理部分错误

这两种方法都是批处理器。如果批处理中的某些项无法解析，则整个请求不会失败并返回顶级错误。相反，API 会返回部分成功响应，您必须检查响应中是否存在单项失败。

解读响应

保证 1:1 对应：返回的 results 列表（对于 ResolveNames）或 entities 列表（对于 ResolveMapsUrls）通过索引与输入列表 1:1 对应。
失败时返回空元素：如果索引 i 处的项未能解析，则结果列表会在索引 i 处包含一个空对象 {}。
failedRequests 映射：响应包含 failedRequests 映射。
- 键是失败项的从 0 开始的索引（在 JSON 中表示为字符串）。
- 该值是一个 google.rpc.Status 对象，其中包含错误代码和说明商品失败原因的消息。
saveToMapsUrl 仅涵盖成功解决的问题：saveToMapsUrl 链接仅包含已解决的问题。不包括失败的内容。

请勿因为一项失败而假设整个批次都失败。请务必检查 failedRequests，了解哪些内容（如有）无法解析。

单项错误

下表列出了您可能会在 failedRequests 中看到的每项错误：

方法	原因	代码	消息
`ResolveNames`	无法将名称或地址解析为地点。	`5` (`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	无法将该网址解析为地点。	`3` (`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
两种方法	解析该项时发生内部错误。	`13` (`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

仅重试失败的项，并使用 INTERNAL。

顶级故障

在以下情况下，API 会返回顶级错误，而不是只答完一部分的回答：

请求无效 (400 INVALID_ARGUMENT)：请求包含超过 20 项内容，ResolveNames 请求没有查询或查询的 text 值为空，或者 ResolveMapsUrls 请求的网址为空或语法无效。一个无效内容会导致整个请求失败。
身份验证、权限或配额错误：例如，API 密钥缺失或无效，或者请求超出了用量限额。
服务器错误 (500 INTERNAL)：重试请求。

将 Resolution API 与 MCP 搭配使用

位于 https://mapstools.googleapis.com/mcp 的地图实验专区智能体工具 MCP 服务器将 Resolution API 公开为两个工具：

resolve_names：将一批地点名称或地址解析为地点 ID。
resolve_maps_urls：将一批 Google 地图网址解析为地点 ID。

当您将 LLM 配置为使用 MCP 服务器时，这些工具会与其他地图实验专区智能体工具一起提供。这些工具接受相同的输入，强制执行相同的限制，并返回与 REST 方法相同的部分失败响应。

工具回答包含 save_to_maps_url 字段。工具说明会指示 LLM 在用户想要将解析后的地点保存、分享或在 Google 地图中以列表形式打开时，提供此链接，而不是自行构建链接。

以下示例使用 curl 直接调用 resolve_names 工具：

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

如需调用 resolve_maps_urls，请将 name 设置为 resolve_maps_urls，并在 arguments 中传递 urls 数组。

REST API 规范和 curl 示例

ResolveNames

方法：POST

https://mapstools.googleapis.com/v1:resolveNames

请求正文格式

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

queries（必需）：要解析的查询的重复列表（最多 20 个）。
locationBias（可选）：视口边界框，用于使结果偏向于本地。
regionCode（可选）：CLDR 国家/地区代码（例如“US”或“FR”），用于使结果偏向于特定国家/地区。

Curl 示例：成功解析

此查询会解析“Googleplex”和“埃菲尔铁塔”。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON 响应

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Curl 示例：混合结果（部分失败）

在此示例中，第一项是无法解析的文本，第二项是有效地点。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON 响应

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

方法：POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

请求正文格式

{
  "urls": [
    "string"
  ]
}

urls（必需）：要解析的 Google 地图网址字符串的重复列表（最多 20 个）。

Curl 示例：成功解析

以下示例会解析标准 Google 地图地点网址：

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON 响应

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl 示例：混合结果（部分失败）

以下示例会解析一个有效地点网址和一个无法解析为地点的网址：

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON 响应

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl 示例：验证失败

以下示例在单个请求中传递了 20 多个网址：

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON 响应

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

发送反馈

如需报告问题或分享有关 Resolution API 的反馈，请使用地图体验智能体工具公开问题跟踪器组件：

Maps Tools Resolution API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

API 访问权限和身份验证

API 密钥

OAuth 2.0 范围

用量限额

价格

请求验证和限制

将解析出的地点保存到 Google 地图

处理部分错误

解读响应

单项错误

顶级故障

将 Resolution API 与 MCP 搭配使用

REST API 规范和 curl 示例

ResolveNames

方法：POST

请求正文格式

Curl 示例：成功解析

JSON 响应

Curl 示例：混合结果（部分失败）

JSON 响应

ResolveMapsUrls

方法：POST

请求正文格式

Curl 示例：成功解析

JSON 响应

Curl 示例：混合结果（部分失败）

JSON 响应

Curl 示例：验证失败

JSON 响应

发送反馈

Maps Tools Resolution API