地点 ID

请选择平台： Android iOS JavaScript 网络服务

地点 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。

使用 Places SDK for Android 的示例

在 Places SDK for Android 中，您可以通过调用 Place.getId() 来检索地点的 ID。地点自动补全服务还会为与所提供的搜索查询和过滤条件匹配的每个地点返回一个地点 ID。稍后，您可以使用地点 ID 再次检索 Place 对象。

如需根据 ID 获取地点，请调用 PlacesClient.fetchPlace()，并传入 FetchPlaceRequest。

该 API 会在 Task 中返回 FetchPlaceResponse。 FetchPlaceResponse 包含与所提供的地点 ID 匹配的 Place 对象。

以下代码示例展示了如何调用 fetchPlace() 来获取指定地点的详细信息。

Kotlin

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

Java

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

保存地点 ID 供日后使用

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

刷新存储的地点 ID

如果地点 ID 存在时间超过 12 个月，我们建议进行刷新。您可以发出地点详情请求，同时仅指定 fields 参数中的 Place.Field.ID 字段，从而免费刷新地点 ID。该调用会触发地点详情 - ID 刷新 SKU。

此请求也可能会返回 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