Places SDK for Android 可為您的應用程式提供豐富的地點相關資訊,包括地點的名稱和地址、以經緯度座標指定的地理位置,以及地點類型 (例如夜店、寵物店、博物館等)。如要存取特定地點的這項資訊,您可以使用地點 ID,這個不重複的識別碼可用於識別特定地點。
地點詳細資訊
Place
物件會提供特定地點的相關資訊。您可以透過下列方式取得 Place
物件:
- 呼叫
PlacesClient.findCurrentPlace()
- 請參閱取得目前地點指南。 - 撥打
PlacesClient.fetchPlace()
- 請參閱依 ID 取得地點指南。
當您要求地點時,必須指定要傳回的地點資料。方法很簡單,只要傳送一個 Place.Field 值清單,以指定要傳回的資料。這份清單是相當重要的考量因素,因為這會影響每項要求的費用。
由於地點資料結果不得留空,因此只有包含資料的地點結果才會傳回 (例如,如果要求的地點沒有相片,則結果中不會顯示 photos
欄位)。
下列範例傳送三個 Place.Field 值的清單,以指定要求傳回的資料:
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
取得 Place
物件後,請使用物件的方法擷取地點資料。以下列舉幾種可用的方法。如需所有方法的完整清單,請參閱 Place
API 參考資料。
getAddress()
:以使用者可理解的格式顯示地點的地址。getAddressComponents()
- 此位置的地址元件的List
。這些元件是用來擷取與地點地址相關的結構化資訊,例如尋找特定地點的城市。請勿使用這些元件進行地址格式設定;請改為呼叫getAddress()
,提供本地化格式的地址。getID()
:地點的文字 ID。請在本頁的其餘部分進一步瞭解地點 ID。getLatLng()
:地點的地理位置,以經緯度座標指定。getName()
- 地點名稱。getOpeningHours()
- 地點的OpeningHours
。呼叫OpeningHours.getWeekdayText()
會傳回字串清單,代表每週每一天的營業時間。呼叫OpeningHours.getPeriods()
會傳回period
物件的清單,其中含有更詳細的資訊,相當於getWeekdayText()
提供的資料。注意:如果地點一律開啟,時間範圍會以星期日午夜表示,且closeEvent
為空值。isOpen()
- 表示地點目前營業中的布林值。如果未指定時間,則預設為預設值。只有在同時提供Place.Field.UTC_OFFSET
和Place.Field.OPENING_HOURS
時,系統才會傳回isOpen
。為確保結果正確,請在原始地點要求中要求Place.Field.BUSINESS_STATUS
和Place.Field.UTC_OFFSET
欄位。如果未要求,系統會假設商家已正常營業。如要瞭解如何搭配isOpen
使用 Place Details,請參閱這部影片。
以下提供幾個簡易的範例:
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
val name = place.name val address = place.address val location = place.latLng
依 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()
以取得指定地點的詳細資料。
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. } });
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") } }
在應用程式中顯示歸因
當應用程式顯示地點資訊時,應用程式也必須顯示出處資訊。請參閱歸因說明文件。
進一步瞭解地點 ID
Places SDK for Android 中使用的地點 ID 與 Places API 中使用的 ID 相同。每個地點 ID 只能參照一個地點,但一個地點可包含多個地點 ID。在某些情況下,可能會造成地點取得新的地點 ID。舉例來說,如果商家要搬遷到新址,就可能會發生這種情況。
透過指定地點 ID 要求地點,您即可確保會在回應中一律收到相同地點 (如果地點仍然存在)。但請注意,回應可能包含的地點 ID 與要求中的地點 ID 不同。
詳情請參閱地點 ID 總覽。