Place Details

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

Places SDK for Android 為應用程式提供豐富的資訊 地點的相關資訊，包括地點的名稱和地址、 指定經緯度座標的位置，以及地點類型 (例如 例如夜店、寵物店、博物館等如要存取這項資訊 特定地點時，您可以使用地點 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敬上 API 參考資料。

  • getAddress()：地點的地址 (人類可讀) 格式。
  • getAddressComponents() - A List 這裡所說的地址元件這些元件是針對 是擷取地點地址的結構化資訊， 範例：尋找地點所在的城市。請勿使用 地址格式元件而是呼叫 getAddress()。 ，提供本地化格式化的地址。
  • getId()：地點的文字 ID。已讀 進一步瞭解本頁其餘部分。
  • getLatLng() - 地點的地理位置。 以經緯度座標表示。
  • getName() - 地點的名稱。

  • getOpeningHours() - OpeningHours 地點。呼叫 OpeningHours.getWeekdayText() 以傳回 代表 一整週。呼叫 OpeningHours.getPeriods() 以傳回 period 物件，其中包含更詳細的資訊 相當於 getWeekdayText() 提供的資料。

    Place 物件也包含 getCurrentOpeningHours() 方法，會傳回地點未來七天的營業時間，且 getSecondaryOpeningHours() ，傳回地點在未來 7 天內的次要營業時間。

  • isOpen()：指出地點是否為布林值的布林值 目前開啟的函式如果您未指定時間，系統會採用預設值。isOpen 只有在 Place.Field.UTC_OFFSET 和 Place.Field.OPENING_HOURS 可供使用。確保準確性 結果，請要求 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()。 Place Autocomplete 服務 也會傳回與所提供搜尋查詢相符的每個地點的地點 ID 和篩選器您可以儲存地點 ID，並使用它來擷取 Place敬上 物件。

如要依 ID 取得地點，請呼叫 PlacesClient.fetchPlace()、 傳遞 FetchPlaceRequest。

API 會傳回 FetchPlaceResponse敬上 風格 Task。 FetchPlaceResponse敬上 包含 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」。

下例決定地點目前是否營業中。在這個例子中， 至 isOpen() 的地點 ID：

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 是相同的 ID 在 Places API 中使用時相同。 每個地點 ID 只能代表一個地點，但一個地點可以有多個地點 多個地點 ID還有其他情況可能會導致地點 取得新的地點 ID舉例來說，如果商家換了新店，可能就會發生這種情形 或 HTTP/HTTPS 位置

指定地點 ID 來要求地點時， 您會在回覆中收到相同位置 (如果地點仍存在 存在)。不過請注意，回應中可能包含地點 ID， 與要求中的編號不同

詳情請參閱 地點 ID 總覽。