地点 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 存在时间超过 12 个月,我们建议进行刷新。您可以发出地点详情请求,同时仅指定 fields
参数中的地点 ID 字段,从而免费刷新地点 ID。
Places API(新)
例如,使用地点详情(新):
https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY
Places API
例如,使用旧版地点详情 API:
https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY
此请求也可能会返回 NOT_FOUND
状态代码。一种策略是存储返回了每个地点 ID 的原始请求。如果某个地点 ID 失效,您可以重新发出相应请求,以获取最新结果。这些结果不一定包含原始地点。不过,此请求会产生费用。
使用地点 ID 时的错误代码
INVALID_REQUEST
状态代码表示指定的地点 ID 无效。如果地点 ID 被截断,或者以其他方式被修改而导致不再正确,就可能会返回 INVALID_REQUEST
。
NOT_FOUND
状态代码表示指定的地点 ID 已作废。如果商家停业或搬迁到新的营业地点,其地点 ID 就可能会作废。由于 Google 地图数据库的更新,地点 ID 可能会发生变化。在这种情况下,地点可能会获得新的地点 ID,旧的 ID 则会返回 NOT_FOUND
响应。
特别是,某些类型的地点 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