Place Details

選取平台： Android iOS JavaScript 網路服務

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

地點詳細資訊

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

要求地點時，您必須指定要傳回的地點資料。如要進行此操作，請傳遞 Place.Field 值清單，指定要傳回的資料。這份清單非常重要，因為會影響每個要求的費用。

由於地點資料結果不可空白，因此系統只會傳回含有資料的地點結果 (例如要求的地點沒有相片時，photos 欄位就不會顯示在結果中)。

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

Java

// Specify the fields to return.
final List placeFields = 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 物件中缺少該欄位，相關的方法會傳回空值。以下列舉幾個可用的方法。如需所有方法的完整清單，請參閱 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，請觀看這部影片。

以下提供一些簡單範例：

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")
        }
    }

取得公開狀態

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()：

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

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

下一個範例顯示了呼叫 isOpen() 並傳遞 Place 物件。Place 物件必須包含有效的地點 ID：

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

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

在應用程式中顯示出處

應用程式顯示地點資訊時，必須一併顯示出處資訊。請參閱歸因說明文件。

進一步瞭解地點 ID

Places SDK for Android 中的地點 ID 與 Places API 中使用的 ID 相同。每個地點 ID 只能參照一個地點，但一個地點可以有多個地點 ID。在其他情況下，可能會導致地點取得新的地點 ID。舉例來說，如果商家已搬遷到新的地點，就有可能發生這種情況。

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

詳情請參閱地點 ID 總覽。