地点 ID

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
选择平台Android iOS JavaScript Web 服务

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

  • 在 Geocoding API 网络服务和地理编码服务(Maps JavaScript API)中检索地点 ID 的地址。
  • 在 Directions API 网络服务和路线服务 (Maps JavaScript API) 中指定出发地、目的地和中间航点。
  • 在 Distance Matrix API 网络服务和 Distance Matrix 服务(Maps JavaScript API)中指定出发地和目的地。
  • 检索 Places API 网络服务、Places SDK for Android、Places SDK for iOS 和 Places Library、JavaScript API 中的地点详情。
  • 在 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 APIMaps JavaScript APIGeocoding APIMaps Embed APIRoads API 中的地点。

使用地点 ID 检索地点详情

地点 ID 不受 Google Maps Platform 服务条款第 3.2.3(b) 条中所述的缓存限制的约束。确定某个地点的地点 ID 后,您可以在下次查找该地点时重复使用该值。如需了解详情,请参阅下文的保存地点 ID 供日后使用

使用地点 ID 的一种常见方法是(例如,使用 Maps JavaScript API 中的 Places APIPlaces 库搜索地点),然后使用返回的地点 ID 来检索地点详情。您可以存储地点 ID,以后使用它来检索相同的地点详情。请参阅下文的保存地点 ID

Places SDK for Android 使用示例

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

如需按 ID 获取地点,请调用 PlacesClient.fetchPlace(),并传递 FetchPlaceRequest

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

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

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.
    }
});

      

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")
        }
    }

      

保存地点 ID 供日后使用

地点 ID 不受 Google Maps Platform 服务条款第 3.2.3(a) 条中所述的缓存限制的约束。因此,您可以存储地点 ID 值以备后用。

刷新存储的地点 ID

如果地点 ID 存在时间超过 12 个月,我们建议您刷新。您可以免费刷新地点 ID,方法是发出地点详情请求,仅在 fields 参数中指定 Place.Field.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