Places SDK for Android 可为您的应用提供有关地点的丰富信息,包括地点的名称和地址、以纬度/经度坐标形式指定的地理位置、地点类型(如夜总会、宠物店、博物馆)等等。如需访问特定地点的这类信息,您可以使用地点 ID,这是一种可唯一标识地点的稳定标识符。
地点详情
Place
对象提供有关特定地点的信息。您可以通过以下方式获取 Place
对象:
- 调用
PlacesClient.fetchPlace()
- 请参阅有关按 ID 获取地点的指南。 - 调用
PlacesClient.findCurrentPlace()
- 请参阅有关获取当前地点的指南。
请求地点时,您必须指定要返回的地点数据。为此,请传递一个 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()
- 地点的文本标识符。请在本页面的其余部分详细了解地点 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 不同。
如需了解详情,请参阅地点 ID 概览。