地点 ID

请选择平台： Android iOS JavaScript 网络服务
欧洲经济区 (EEA) 开发者

简介

地点 ID 可唯一标识 Google Places 数据库中和 Google 地图上的地点。向以下 Maps API 发出的请求可以接受地点 ID：

  • 在 Geocoding API 和 Maps JavaScript API 地理编码服务中检索地点 ID 对应的地址。
  • 在 Routes API 和 Directions API（旧版）以及 Maps JavaScript API（旧版）路线服务中指定出发地、目的地和中间航点。
  • 在 Routes API 及 Distance Matrix API（旧版）和 Maps JavaScript API 距离矩阵服务（旧版）中指定出发地和目的地。
  • 在 Places API（新）、Places SDK for Android（新）、Places SDK for iOS（新）和地点库中检索地点详情。
  • 在 Maps Embed API 中使用地点 ID 参数。
  • 在地图网址中检索搜索查询。
  • 在 Roads API 中显示速度限制。
  • 查找边界多边形并为其设置边界的数据驱动型样式。

查找特定地点的 ID

想查找特定地点的地点 ID？可以使用下面的地点 ID 查找工具来搜索地点并获取其 ID：

或者，您也可以在 Maps JavaScript API 文档中查看地点 ID 查找工具及其代码。

概览

地点 ID 是唯一标识地点的文本标识符。标识符的长度可能会有所不同（地点 ID 没有长度上限）。示例：

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

地点 ID 适用于大多数位置，包括商家、地标、公园和交叉路口。同一地点或位置可以有多个不同的地点 ID。地点 ID 可能会随时间而变化。

您可以在 Places API 和多个 Google Maps Platform API 中使用同一地点 ID。例如，您可以使用同一地点 ID 在 Places API、Maps JavaScript API、Geocoding API、Maps Embed API 和 Roads API 中引用地点。

使用地点 ID 检索地点详情

使用地点 ID 的一种常见方式是搜索地点（例如使用 Places API 或 Maps JavaScript API 中的地点库），然后使用返回的地点 ID 来检索地点详情。您可以存储地点 ID，日后再使用它来检索相同地点详情。请参阅下文的保存地点 ID。

以下示例展示了如何为地点 API（新版）和地点 API（旧版）请求图标网址。

Places API（新）

使用 Places API，您可以通过发出文本搜索（新）请求来查找地点 ID。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

响应中的 id 字段包含地点 ID，如下所示：

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

现在，您可以通过在请求网址中添加地点 ID 来发出地点详情（新）请求：

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API（旧版）

使用 Places API，您可以通过发出地点搜索请求来查找地点 ID。

以下示例是一个搜索请求，用于查找澳大利亚悉尼某个地点半径 1500 米范围内包含“游轮”字样的“餐厅”类型地点：

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

响应中的 place_id 字段包含地点 ID，如以下代码段所示：

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

现在，您可以发送地点详情（旧版）请求，并将地点 ID 放入 place_id 参数中：

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

保存地点 ID 供日后使用

地点 ID 不受 Google Maps Platform 服务条款第 3.2.3(b) 条中规定的缓存限制的约束。因此，您可以存储地点 ID 值以供日后使用。

刷新存储的地点 ID

由于地点 ID 可能会因 Google 地图数据库更新而发生变化，因此 Google 建议您在地点 ID 存在时间超过 12 个月时进行刷新。您可以发出地点详情请求，同时仅指定 fields 参数中的地点 ID 字段，从而免费刷新地点 ID。

Places API（新）

例如，使用地点详情（新）：

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API（旧版）

例如，使用 Places API（旧版）：

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

此调用会触发地点详情（仅限新必需 ID）或地点详情 - ID 刷新 SKU。

使用地点 ID 时的错误代码

INVALID_REQUEST

INVALID_REQUEST 状态代码表示指定的地点 ID 无效。如果地点 ID 被截断，或者以其他方式被修改而导致不再正确，就可能会返回 INVALID_REQUEST。

NOT_FOUND

NOT_FOUND 状态代码表示指定的地点 ID 已作废。如果商家停业或搬迁到新的营业地点，其地点 ID 就可能会作废。由于 Google 地图数据库的更新，地点 ID 也可能会发生变化。在这种情况下，地点可能会获得新的地点 ID，旧的 ID 则会返回 NOT_FOUND 响应。

如需在出现过时地点 ID 时刷新结果，请存储返回每个地点 ID 的原始请求，并根据需要重新发出请求。请注意，重新发出的请求将按相应的 SKU 进行结算。

某些类型的地点 ID 有时可能会导致 NOT_FOUND 响应，或者 API 可能会在响应中返回不同的地点 ID。这些地点 ID 类型包括：

  • 街道地址，这类地址并不是 Google 地图中的精确地址，而是从一系列地址中推断出来的。
  • 长路线的路段，其中请求还指定了城市或市行政区。
  • 交叉路口。
  • 包含 subpremise 类型的地址组成部分的地点。

这些 ID 通常采用长字符串的形式（地点 ID 没有长度上限）。例如：

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4