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
字段。 如果未要求,Google 就假定商家仍在运营。 请观看此视频,了解如何将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()
提取这些字段。如需详细了解如何使用必填字段创建地点对象,请参阅地点详情。
以下示例用于确定某个地点当前是否营业。在此示例中,您只需将地点 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()); // ... }); // ...
在应用中显示提供方说明
如果您的应用要显示地点信息(包括地点评价),则还必须显示任何提供方说明。如需了解详情,请参阅归因。
更多关于地点 ID 的内容
Places SDK for Android 中使用的地点 ID 与 Places API 中使用的标识符相同。 每个地点 ID 只能指代一个地点,但单个地点可以有多个地点 ID。还有其他情况可能会导致地点获取新的地点 ID。例如,如果商家搬迁到新的营业地点,就可能会发生这种情况。
通过指定地点 ID 请求地点时,您可以确信将始终在响应中收到同一地点(如果该地点仍然存在)。但请注意,响应中包含的地点 ID 可能不同于您的请求中的地点 ID。
如需了解详情,请参阅地点 ID 概览。