Place Details

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

地點詳細資訊

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

要求地點時,您必須指定要傳回的地點資料類型。為此,請傳遞 List<Place.Field>,指定要傳回的資料類型。這是非常重要的考量因素,因為這會影響每項要求的費用。由於地點資料結果不得留空,因此系統只會傳回含有資料的地點結果 (例如,如果要求的地點沒有相片,則結果不會顯示 photos 欄位)。您可以指定下列一或多個欄位:

  • Place.Field.ADDRESS
  • Place.Field.ADDRESS_COMPONENTS
  • Place.Field.BUSINESS_STATUS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.ICON_URL
  • Place.Field.ICON_BACKGROUND_COLOR
  • Place.Field.VIEWPORT
  • Place.Field.UTC_OFFSET
  • Place.Field.WEBSITE_URI

進一步瞭解地點欄位。如要進一步瞭解地點資料要求的計費方式,請參閱用量與帳單

使用下列方法從 Place 擷取資料:

  • getAddress():地點使用者可理解的地址和位置。
  • getAddressComponents() - 包含此地點的地址元件 List。提供這些元件是為了擷取地點地址的結構化資訊,例如尋找地點所在的城市。請勿使用這些元件進行地址格式設定;請改為呼叫 getAddress(),以便提供本地化格式的地址。
  • getBusinessStatus() - 地點的營運狀態。可包含下列其中一個值:OPERATIONALCLOSED_TEMPORARILYCLOSED PERMANENTLY
  • getAttributions() - 使用地點資料時,必須向使用者顯示的出處。
  • getID():地點的文字 ID。請參閱本頁面的其他部分,進一步瞭解地點 ID。
  • getLatLng():地點的地理位置,以經緯度座標指定。
  • getName() - 地點名稱。
  • getOpeningHours() - 地點的 OpeningHours。呼叫 OpeningHours.getWeekdayText() 會傳回字串清單,代表一週中的每一天的營業時間。呼叫 OpeningHours.getPeriods() 即可傳回 period 物件清單,提供與 getWeekdayText() 提供的詳細資訊的詳細資訊。注意:如果地點一律開啟,時間範圍會以星期日午夜表示,closeEvent 為空值。
  • getPhoneNumber() - 地點的電話號碼。
  • getPhotoMetadatas() - 與地點相關聯的相片相關中繼資料,包括點陣圖圖片。
  • getPlusCode():此地點的 PlusCode 位置。
  • getPriceLevel() - 此地點的價格等級,以 0 (最低) 至 4 (最高) 之間的整數傳回。
  • getRating() - 地點的綜合評分;以浮點值表示,傳回值介於 1.0 至 5.0 之間的值 (依據使用者匯總評論)。
  • getTypes():用於識別這個地點的地點類型清單。如需可用地點類型清單,請參閱 Place 介面的說明文件。
  • getUserRatingsTotal() - 此地點的使用者評分總次數。
  • getIconUrl():代表地點類型的黑色圖示遮罩網址。
  • getIconBackgroundColor - 地點類型的圖示背景顏色。
  • getUtcOffsetMinutes():世界標準時間偏移 (分鐘)。
  • getViewport() - 以 LatLngBounds 物件形式傳回的可視區域,可用來在地圖上顯示地點。如果該地點的大小不明,可能會傳回空值。
  • getWebsiteUri() - 地點網站的 URI (如果已知)。這是指由商家或其他與地點相關聯的實體所維護的網站。如果不知道網站,則傳回空值。
  • isOpen() - 表示地點目前營業中的布林值。如果未指定時間,則預設為預設值。只有在同時具備 Place.Field.UTC_OFFSETPlace.Field.OPENING_HOURS 時,系統才會傳回 isOpen。為確保準確的結果,請在原始地點要求中要求 Place.Field.BUSINESS_STATUSPlace.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 中傳回 FetchPlaceResponseFetchPlaceResponse 包含與提供的地點 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 總覽