地点详情

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

Places SDK for Android 为您的应用提供有关地点的丰富信息，包括地点的名称和地址、以纬度/经度坐标指定的地理位置、地点类型（如夜总会、宠物店、博物馆）等。如需访问特定地点的此类信息，您可以使用地点 ID，即唯一标识地点的稳定标识符。

地点详情

Place 对象可提供有关特定地点的信息。您可以通过以下方式获取 Place 对象：

• 调用 PlacesClient.findCurrentPlace() - 请参阅有关获取当前地点的指南。
• 调用 PlacesClient.fetchPlace() - 请参阅有关按 ID 获取地点的指南。

请求地点时，您必须指定要返回的地点数据。为此，请传递 Place.Field 值的列表，指定要返回的数据。此列表是一个重要的考虑因素，因为它会影响每个请求的费用。

由于地点数据结果不得为空，因此系统只会返回包含数据的地点结果（例如，如果请求的地点没有照片，photos 字段将不会出现在结果中）。

以下示例会传递三个 Place.Field 值的列表，以指定请求返回的数据：

Java

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

Kotlin

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

注意：findCurrentPlace() 和 fetchPlace() 支持不同的字段集。findCurrentPlace() 不支持以下字段：Place.Field.ADDRESS_COMPONENTS、Place.Field.CURBSIDE_PICKUP、Place.Field.DELIVERY、Place.Field.DINE_IN、Place.Field.OPENING_HOURS、Place.Field.PHONE_NUMBER、Place.Field.TAKEOUT、Place.Field.UTC_OFFSET 和 Place.Field.WEBSITE_URI。

获取 Place 对象后，请使用该对象的方法检索地点数据。下面给出了几种可用方法的示例。如需查看所有方法的完整列表，请参阅 Place API 参考文档。

• getAddress() - 地点的地址（采用人类可读懂的格式）。
• getAddressComponents() - 此地点的地址组成部分的 List。提供这些组件的目的是提取有关地点地址的结构化信息，例如查找地点所在的城市。请勿使用这些组件设置地址格式，而应调用 getAddress()，以提供本地化格式的地址。
• getID() - 地点的文本标识符。如需详细了解地点 ID，请参阅本页面的其余部分。
• getLatLng() - 地点的地理位置，由纬度和经度坐标指定。
• getName() - 地点的名称。
• getOpeningHours() - 地点的 OpeningHours。调用 OpeningHours.getWeekdayText() 可返回一个字符串列表，表示一周中每天的营业时间和结束营业时间。调用 OpeningHours.getPeriods() 会返回 period 对象列表，其中包含更详细的信息，等同于 getWeekdayText() 提供的数据。注意：如果某个地点一直营业，则时间段会显示为星期日的午夜，且 closeEvent 为 null。
• isOpen() - 表示地点当前是否营业的布尔值。如果未指定时间，则现在为默认值。仅当 Place.Field.UTC_OFFSET 和 Place.Field.OPENING_HOURS 都可用时，才会返回 isOpen。为确保结果准确，请请求原始地点请求中的 Place.Field.BUSINESS_STATUS 和 Place.Field.UTC_OFFSET 字段。如果未提出请求，则假定商家已正常运行。如需了解如何将 isOpen 与地点详情结合使用，请观看此视频。

以下是一些简单示例：

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

按 ID 获取地点

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

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

该 API 会在 Task 中返回 FetchPlaceResponse。FetchPlaceResponse 包含一个与所提供的地点 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")
        }
    }

      

您可以使用 CancellationToken 来尝试取消发送给任何请求类（例如 FetchPlaceRequest）的请求。取消操作是尽力完成的。发出取消请求后，将不会返回任何响应。发出取消令牌不能保证特定请求会被取消；即使未返回任何响应，您可能仍会为该请求付费。

在应用中显示提供方说明

当应用显示地点信息时，还必须显示提供方说明。请参阅有关归因的文档。

更多关于地点 ID 的内容

Places SDK for Android 中使用的地点 ID 与 Places API 中使用的标识符相同。每个地点 ID 只能引用一个地点，但单个地点可以有多个地点 ID。还有其他一些情况可能会导致地点获得新的地点 ID。例如，如果商家搬迁到新地点，就可能发生这种情况。

通过指定地点 ID 请求地点时，您可以确信始终会在响应中收到相同的地点（如果该地点仍然存在）。但请注意，响应中包含的地点 ID 可能与您请求中的地点 ID 不同。

如需了解详情，请参阅地点 ID 概览。