Place Details

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

地點詳細資訊

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

要求地點時，您必須指定要傳回哪些地點資料。如要這樣做，請傳遞 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 物件中缺少欄位，相關方法會傳回 null。以下列舉幾種可用方法的範例。

  • 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 詳細資料」。

以下範例會判斷地點目前是否營業。在本例中，您只會將地點 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());
            // ...
        });
// ...

在應用程式中顯示出處資訊

當應用程式顯示地點資訊 (包括地點評論) 時，也必須顯示相關出處資訊。詳情請參閱歸因。

進一步瞭解 Place ID

Places SDK for Android 使用的地點 ID 與 Places API 使用的 ID 相同。每個地點 ID 只能指向一個地點，但單一地點可有多個地點 ID。其他情況也可能導致地點獲得新地點 ID。舉例來說，如果商家搬遷至新地點，就可能發生這種情況。

當您透過指定地點 ID 要求地點時，您可以確信在回應中一律會收到相同的地點 (如果地點仍存在的話)。不過請注意，回應中可能包含的地點 ID 與要求中的 ID 不同。

詳情請參閱地點 ID 總覽。