新一代 Places SDK for Android 现已随着 Places SDK for Android（新）的发布而推出。

此页面由 Cloud Translation API 翻译。

地点详情

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

Places SDK for Android 可为您的应用提供丰富的信息包括地点的名称和地址、地理位置以纬度/经度坐标形式指定的位置、地点类型（例如例如夜总会、宠物店、博物馆）等等。要访问那么您可以使用地点 ID，用于标识地点。

地点详情

通过 Place 对象提供有关特定地点的信息。您可以拿到 Place 对象：

致电 PlacesClient.fetchPlace() – 请参阅按 ID 获取地点。
致电 PlacesClient.findCurrentPlace() – 请参阅获取当前地点。
同时 PlacesClient.fetchPlace() 支持所有地点数据字段， PlacesClient.findCurrentPlace() 仅支持一部分地点数据字段。对于字段列表，受 findCurrentPlace() 支持，请参阅 Places SDK for Android 字段支持。

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

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

以下示例传递了一个列表，其中包含三个 Place.Field 值指定请求返回的数据：

Kotlin

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

Java

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

访问地点对象数据字段

获取 Place 对象后，请使用该对象的方法来访问数据字段。如果 Place 对象中缺少该字段，相关方法会返回 null。下面显示了一些可用方法的示例。有关所有方法的完整列表，请参阅 Place API 参考文档。

getAddress() - 以直观易懂的方式表示的地点地址格式。
getAddressComponents() – List 这个地方的地址组成部分。这些组件是为用于提取有关地点地址的结构化信息，查找某个地点所在的城市的示例。请勿使用地址格式组件；而是调用 getAddress()。这会提供采用本地化格式的地址
getId() - 地点的文本标识符。已读。
getLatLng() - 地点的地理位置；以纬度和经度坐标形式指定。
getName() - 地点的名称。
getOpeningHours() – OpeningHours 位置。调用 OpeningHours.getWeekdayText() 以返回代表以下日期的每一天的营业时间和打烊时间的字符串列表。调用 OpeningHours.getPeriods() 可返回 period 对象，其中包含更详细的信息，相当于 getWeekdayText() 提供的数据。

注意：如果某个地点始终处于营业状态，则时间段表示为星期日午夜，closeEvent 为 null。

Place 对象还包含 getCurrentOpeningHours() 方法，该方法会返回地点未来 7 天的营业时间；以及 getSecondaryOpeningHours() 返回地点接下来七天内的次要营业时间。
isOpen() - 一个布尔值，表示该地点是否位于当前打开。如果未指定时间，则默认值为现在。isOpen 仅当 Place.Field.UTC_OFFSET 和 Place.Field.OPENING_HOURS 可用。为确保准确请求 Place.Field.BUSINESS_STATUS 和原始地点请求中的 Place.Field.UTC_OFFSET 字段。如果未要求，Google 就认定商家正在营业。请观看此视频，了解如何使用 isOpen（含地点详情）。

注意：此方法已废弃。请改用 PlacesClient.isOpen(IsOpenRequest request)。有关详情，请参阅获取营业状态。

以下是一些简单示例：

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，并使用它来检索 Place 对象。

要按 ID 获取地点，请调用 PlacesClient.fetchPlace()、传递 FetchPlaceRequest。

该 API 会返回一个 FetchPlaceResponse 以 Task。通过 FetchPlaceResponse 包含 Place 对象与提供的地点 ID 相匹配。

以下代码示例展示了如何调用 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，请参阅初始化 Places API 客户端。

获取营业状态

PlacesClient.isOpen(IsOpenRequest request) 方法会返回一个 IsOpenResponse 对象，指明该地点是否目前在通话中指定的时间处于营业状态。

此方法接受 IsOpenRequest 类型的单个参数，该参数中包含：

Place 对象或用于指定地点 ID 的字符串。
注意：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 对象，请参阅地点详情。

注意：地点的基本数据 SKU 支付 Place.Field.UTC_OFFSET 对 fetchPlace() 的通话费用； Place.Field.BUSINESS_STATUS。地点联系人数据 SKU 为 Place.Field.CURRENT_OPENING_HOURS 拨打 fetchPlace() 需付费和 Place.Field.OPENING_HOURS。

以下示例用于确定某个地点当前是否营业。在此示例中，您只将将地点 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());
// ...

下一个示例展示了如何在传递 Place 对象的情况下调用 isOpen()。 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());
            // ...
        });
// ...

在应用中显示提供方说明

如果您的应用要显示地点信息（包括地点评价），则还必须显示任何提供方说明。如需了解详情，请参阅归因。

地点详情

地点详情

Kotlin

Java

访问地点对象数据字段

Kotlin

Java

按 ID 获取地点

Kotlin

Java

获取营业状态

Kotlin

Java

Kotlin

Java

在应用中显示提供方说明

更多关于地点 ID 的内容