Place Details

Places SDK for Android 可為您的應用程式提供豐富的地點相關資訊，包括地點的名稱和地址、以經緯度座標指定的地理位置，以及地點類型 (例如夜店、寵物店、博物館等)。如要存取特定地點的這項資訊，您可以使用地點 ID，這個不重複的識別碼可用於識別特定地點。

地點詳細資訊

Place 物件會提供特定地點的相關資訊。您可以透過下列方式取得 Place 物件：

• 呼叫 PlacesClient.findCurrentPlace() - 請參閱取得目前地點指南。
• 撥打 PlacesClient.fetchPlace() - 請參閱依 ID 取得地點指南。

當您要求地點時，必須指定要傳回的地點資料。方法很簡單，只要傳送一個 Place.Field 值清單，以指定要傳回的資料。這份清單是相當重要的考量因素，因為這會影響每項要求的費用。

由於地點資料結果不得留空，因此只有包含資料的地點結果才會傳回 (例如，如果要求的地點沒有相片，則結果中不會顯示 photos 欄位)。

下列範例傳送三個 Place.Field 值的清單，以指定要求傳回的資料：

// Specify the fields to return.
final List placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

// 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，請參閱這部影片。

以下提供幾個簡易的範例：

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

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() 以取得指定地點的詳細資料。

// 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.
    }
});

      

// 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 總覽。