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,日後再次使用該 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 不同。
詳情請參閱地點 ID 總覽。