Maps Tools Resolution API（实验性）

Maps Tools Resolution API 提供批量处理端点，用于将位置名称和网址解析为 Google 地图地点 ID。

API 访问和身份验证

身份验证方式

这些 API 支持 API 密钥 和 OAuth 2.0 凭据：

1. API 密钥

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 范围

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

  • https://www.googleapis.com/auth/maps-platform.mapstools（推荐）

请求验证和限制

为防止过多的负载并确保快速响应，系统会对批量请求进行严格验证：

  • 批量大小限制：这两个 API 都允许每个请求最多包含 20 个项。
  • ResolveNames 要求:
    • 每个 queries 项都必须指定一个非空文本参数。
    • 查询必须表示特定的地点名称或地址（例如“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）以及未指向单个唯一地点的网址。

处理部分错误

这两个 API 都设计为批量处理器。如果批处理中的某些项无法解析，则整个请求不会失败 并显示顶级错误。相反，API 会返回部分成功 响应。

如何解读响应

  1. 保证 1:1 对齐：返回的结果（对于 ResolveNames）或 实体（对于 ResolveMapsUrls）列表与输入列表1:1 映射。
  2. 失败的空元素：如果索引 i 处的项无法解析， 则结果列表将在索引 i 处包含一个空对象 {}。
  3. failedRequests 映射：响应包含 failedRequests 映射。
    • 键 是失败项的从 0 开始的索引（在 JSON 中表示为字符串）。
    • 值 是一个 google.rpc.Status 对象，其中包含特定错误代码（来自标准 gRPC/HTTP 状态）以及详细说明失败原因的消息。

顶级故障

仅当请求验证失败时（例如，传递的项超过 20 个或缺少必填字段），才会返回顶级 HTTP 错误（例如 400 Bad Request）。

API 规范和 Curl 示例

1. ResolveNames API

方法：POST

https://mapstools.googleapis.com/v1alpha: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”和“Eiffel Tower”。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
JSON 响应
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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/v1alpha:resolveNames?key=KEY"
JSON 响应
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

方法：POST

https://mapstools.googleapis.com/v1alpha: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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON 响应
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON 响应
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

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/v1alpha:resolveMapsUrls?key=KEY"
JSON 响应
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}