Places SDK for Android 可在應用程式中提供豐富的地點相關資訊,包括地點的名稱和地址、指定為經緯度座標的地理位置,以及地點類型 (例如夜店、寵物店和博物館) 等等。如要存取特定地點的這類資訊,可以使用地點 ID (用來識別特定地點的穩定 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
物件中缺少該欄位,相關方法會傳回空值。以下列舉幾種可用方法的範例。如需所有方法的完整清單,請參閱 Place
API 參考資料。
getAddress()
:地點的地址,採用人類可讀的格式。getAddressComponents()
- 這個地點的地址元件List
。這些元件旨在擷取地點地址的相關結構化資訊,例如找出地點所在的城市。請勿將這些元件用於地址格式,而是呼叫getAddress()
來取得本地化格式的地址。getId()
:地點的文字 ID。請參閱本頁其他部分的內容,進一步瞭解地點 ID。getLatLng()
:地點的地理位置,以經緯度座標指定。getName()
- 地點的名稱。getOpeningHours()
:地點的OpeningHours
。呼叫OpeningHours.getWeekdayText()
會傳回字串清單,代表一週內每天的營業時間和打烊時間。呼叫OpeningHours.getPeriods()
會傳回period
物件清單,其中含有更詳細的資訊,等同getWeekdayText()
提供的資料。Place
物件還包含getCurrentOpeningHours()
方法,會傳回未來七天的地點營業時間,以及getSecondaryOpeningHours()
會傳回地點在接下來七天內的次要營業時間。isOpen()
:布林值,指出地點目前是否為營業中。如果沒有指定時間,系統會採用預設值。只有在Place.Field.UTC_OFFSET
和Place.Field.OPENING_HOURS
都可用時,系統才會傳回isOpen
。為確保結果正確無誤,請在原始地點要求中要求Place.Field.BUSINESS_STATUS
和Place.Field.UTC_OFFSET
欄位。如未要求,我們會假設商家已恢復營業。如要瞭解如何搭配 Place Details 使用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 是用來識別特定地點的文字 ID,在 Places SDK for Android 中,您可以呼叫 Place.getId()
來擷取地點 ID。Place Autocomplete 服務也會為每個地點傳回與提供搜尋查詢和篩選器相符的地點 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 物件,請參閱 Place Details。
以下範例可判斷地點目前是否營業中。在這個範例中,您只將地點 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 總覽。