地点详情

欧洲经济区 (EEA) 开发者

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

地点详情

Place 对象可提供有关特定地点的信息。您可以通过调用 PlacesClient.fetchPlace() 来获取 Place 对象 - 请参阅按 ID 获取地点指南。

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

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

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

Kotlin

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

Java

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

访问 Place 对象数据字段

获取 Place 对象后，使用该对象的方法访问请求中指定的数据字段。如果 Place 对象中缺少相应字段，相关方法会返回 null。下面展示了一些可用方法的示例。

  • getAddress() - 地点的地址，采用人类可读的格式。
  • getAddressComponents() - 相应地点的地址组成部分的 List。这些组件旨在提取有关地点地址的结构化信息，例如查找地点所在的城市。请勿使用这些组件来设置地址格式；而应调用 getAddress()，该方法可提供本地化的格式化地址。
  • getId() - 地点的文本标识符。如需详细了解地点 ID，请参阅本页面的其余部分。
  • getLatLng() - 地理位置，以纬度和经度坐标的形式指定。
  • getName() - 地点的名称。

  • getOpeningHours() - 地点的 OpeningHours。调用 OpeningHours.getWeekdayText() 可返回一个字符串列表，其中包含一周内每天的营业时间和闭店时间。调用 OpeningHours.getPeriods() 可返回一个 period 对象列表，其中包含与 getWeekdayText() 提供的数据等效的更详细信息。

    Place 对象还包含 getCurrentOpeningHours() 方法（用于返回未来 7 天内的营业时间）和 getSecondaryOpeningHours() 方法（用于返回未来 7 天内的次要营业时间）。

  • isOpen() - 一个布尔值，表示相应地点目前是否正在营业。如果未指定时间，则默认为当前时间。只有当 Place.Field.UTC_OFFSET 和 Place.Field.OPENING_HOURS 都可用时，才会返回 isOpen。为确保结果准确，请在原始地点请求中请求 Place.Field.BUSINESS_STATUS 和 Place.Field.UTC_OFFSET 字段。 如果未请求，则假定商家处于营业状态。 请观看此视频，了解如何将 isOpen 与“地点详情”搭配使用。

一些示例：

Kotlin

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

Java

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

按 ID 获取地点

地点 ID 是唯一标识地点的文本标识符。在 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.
    }
});

获取营业状态

PlacesClient.isOpen(IsOpenRequest request) 方法会返回一个 IsOpenResponse 对象，用于指示相应地点是否在调用中指定的时间段内营业。

此方法接受一个类型为 IsOpenRequest 的实参，其中包含：

  • Place 对象，或指定地点 ID 的字符串。
  • 一个可选的时间值，用于指定自 1970-01-01T00:00:00Z 以来的时间（以毫秒为单位）。如果未指定时间，则默认为当前时间。

此方法要求 Place 对象中存在以下字段：

  • Place.Field.BUSINESS_STATUS
  • Place.Field.CURRENT_OPENING_HOURS
  • Place.Field.OPENING_HOURS
  • Place.Field.UTC_OFFSET

如果 Place 对象中未提供这些字段，或者您传递了地点 ID，该方法会使用 PlacesClient.fetchPlace() 来提取这些字段。如需详细了解如何创建包含必要字段的 Place 对象，请参阅地点详情。

以下示例用于确定某个地点目前是否营业。在此示例中，您仅将地点 ID 传递给 isOpen()：

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

下一个示例展示了如何调用 isOpen() 并传递 Place 对象。Place 对象必须包含有效的地点 ID：

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

在应用中显示提供方说明

当您的应用显示地点信息（包括地点评价）时，还必须显示所有提供方信息。如需了解详情，请参阅提供方信息。

更多关于地点 ID 的内容

Places SDK for Android 中使用的地点 ID 与 Places API 中使用的标识符相同。 每个地点 ID 只能指代一个地点，但一个地点可以有多个地点 ID。在其他情况下，地点也可能会获得新的地点 ID。例如，如果商家搬迁到新的营业地点，就可能会发生这种情况。

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

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