Place Details (最新)

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

您可以使用特定機構或景點的地點 ID，提出 Place Details (新版) 要求，以便取得更多相關詳細資料。Place Details (新版) 會傳回指定地點的更完整資訊，例如完整地址、電話號碼、使用者評分和評論。

取得地點 ID 的方法有很多種，例如：

• 文字搜尋 (新版)
• Nearby Search (新版)
• 自動完成 (新功能)

注意： Places Details (新版) 適用於 Places SDK for Android 3.3.0 以上版本。詳情請參閱「選擇 SDK 版本」。如要進一步瞭解如何使用在 4.0.0 版中新增的 Kotlin API，請參閱「參考總覽」。

Place Details (New) 要求

您可以呼叫 PlacesClient.fetchPlace()，並傳遞包含地點 ID 和欄位清單的 FetchPlaceRequest 物件，以及任何選用參數，以便要求地點詳細資料：

// Define a place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList("INSERT_PLACE_FIELDS_HERE");

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

您可以使用 CancellationToken，嘗試取消對任何要求類別 (例如 FetchPlaceRequest) 的請求。系統會盡力取消。提出取消要求後，系統不會回覆。發出取消權杖並非保證特定要求會取消，而且即使沒有傳回回應，您仍可能會因要求而遭到收費。

Place Details (新版) 回應

Place Details (新版) 會以 Place 物件形式傳回資料，其中只包含您使用欄位清單要求的欄位。地點資料結果不可空白，因此系統只會傳回含有資料的地點結果 (例如，如果要求的地點沒有相片，結果中就不會顯示相片欄位)。

如要存取資料欄位，請呼叫對應的方法。舉例來說，如要存取地點名稱，請呼叫 getName()。

必要參數

FetchPlaceRequest 的必要參數如下：

• 地點 ID

  用於識別特定地點的文字 ID，由 Text Search (新版)、Nearby Search (新版) 或 Autocomplete (新版) 傳回。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。

• 欄位清單

  要求地點時，您必須指定要傳回哪些地點資料。如要執行這項操作，請傳遞 Place.Field 值清單，指定要傳回的資料。回應中沒有傳回欄位的預設清單。

  欄位清單是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。此清單是重要的考量因素，因為它會影響每項要求的費用。詳情請參閱「用量與計費」一文。

  指定下列一或多個欄位：

  • 下列欄位會觸發 Place Details (IDs Only) SKU：

    Place.Field.DISPLAY_NAME、Place.Field.ID、Place.Field.PHOTO_METADATAS、Place.Field.RESOURCE_NAME、
    
    注意事項：

    • Place.Field.NAME 欄位已在 Places SDK for Android 4.0 版中淘汰。改用 Place.Field.DISPLAY_NAME。
    • RESOURCE_NAME 欄位包含地點資源名稱，格式為 places/PLACE_ID。使用 DISPLAY_NAME 存取地點的文字名稱。

  • 下列欄位會觸發 Place Details (Location Only) SKU：

    Place.Field.ADDRESS_COMPONENTS、ADR_FORMAT_ADDRESS、Place.Field.FORMATTED_ADDRESS、Place.Field.LOCATION、Place.Field.PLUS_CODE、Place.Field.SHORT_FORMATTED_ADDRESS、Place.Field.TYPES、Place.Field.VIEWPORT、
    
    注意：Place.Field.ADDRESS 和 Place.Field.LAT_LNG 欄位已在 Places SDK for Android 4.0 版中淘汰。請改用 Place.Field.FORMATTED_ADDRESS 和 Place.Field.LOCATION。

  • 以下欄位會觸發 Place Details (Basic) SKU：

    Place.Field.ACCESSIBILITY_OPTIONS、Place.Field.BUSINESS_STATUS、Place.Field.GOOGLE_MAPS_URI、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_MASK_URL、Place.Field.PRIMARY_TYPE、Place.Field.PRIMARY_TYPE_DISPLAY_NAME、Place.Field.SUB_DESTINATIONS、Place.Field.UTC_OFFSET、
    
    注意：在 Places SDK for Android 4.0 版中，Place.Field.ICON_URL 和 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE 欄位已淘汰。請改用 Place.Field.ICON_MASK_URL 和 Place.Field.ACCESSIBILITY_OPTIONS。Place.Field.ACCESSIBILITY_OPTIONS 僅適用於 Place Details (新版)。

  • 下列欄位會觸發 Place Details (Advanced) SKU：

    Place.Field.CURRENT_OPENING_HOURS、Place.Field.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_PHONE_NUMBER、Place.Field.NATIONAL_PHONE_NUMBER、Place.Field.OPENING_HOURS、Place.Field.PRICE_LEVEL、Place.Field.RATING、Place.Field.SECONDARY_OPENING_HOURS、Place.Field.USER_RATING_COUNT、Place.Field.WEBSITE_URI、
    
    注意：Place.Field.PHONE_NUMBER 和 Place.Field.USER_RATINGS_TOTAL 欄位已在 Places SDK for Android 4.0 版中淘汰。請改用 Place.Field.INTERNATIONAL_PHONE_NUMBER 和 Place.USER_RATING_COUNT。

  • 以下欄位會觸發 Place Details (Preferred) SKU：

    Place.Field.ALLOWS_DOGS、 Place.Field.CURBSIDE_PICKUP、 Place.Field.DELIVERY、 Place.Field.DINE_IN、 Place.Field.EDITORIAL_SUMMARY、 Place.Field.EV_CHARGE_OPTIONS、 Place.Field.FUEL_OPTIONS、 Place.Field.GOOD_FOR_CHILDREN、 Place.Field.GOOD_FOR_GROUPS、 Place.Field.GOOD_FOR_WATCHING_SPORTS、 Place.Field.LIVE_MUSIC、 Place.Field.MENU_FOR_CHILDREN、 Place.Field.OUTDOOR_SEATING、 Place.Field.PARKING_OPTIONS、 Place.Field.PAYMENT_OPTIONS、 Place.Field.RESERVABLE、 Place.Field.RESTROOM、 Place.Field.REVIEWS、 Place.Field.SERVES_BEER、 Place.Field.SERVES_BREAKFAST、 Place.Field.SERVES_BRUNCH、 Place.Field.SERVES_COCKTAILS、 Place.Field.SERVES_COFFEE、 Place.Field.SERVES_DESSERT、 Place.Field.SERVES_DINNER、 Place.Field.SERVES_LUNCH、 Place.Field.SERVES_VEGETARIAN_FOOD、 Place.Field.SERVES_WINE、 Place.Field.TAKEOUT
  注意：Places SDK for Android 4.0 版本已淘汰多個 Place 資料欄位，並新增其他欄位。詳情請參閱「 遷移至 Places SDK for Android 4.0 中的新地點資料欄 」。

選用參數

FetchPlaceRequest 的選用參數如下：

• 區域代碼

  用於格式化回應的區碼，指定為 兩個字元的 CLDR 代碼值。沒有預設值。

  如果回應中 Place.Field.FORMATTED_ADDRESS 欄位的國家/地區名稱與 regionCode 相符，Place.Field.FORMATTED_ADDRESS 就會省略國家/地區代碼。

  大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。

  如要設定區域代碼參數，請在建構 FetchPlaceRequest 物件時呼叫 setRegionCode() 方法。

• 工作階段符記

  工作階段符記是使用者產生的字串，可追蹤 Autocomplete (New) 呼叫的「工作階段」。Autocomplete (New) 會使用工作階段符記，將使用者自動完成搜尋的查詢和地點選取階段歸入不同的工作階段，以用於計費。系統會將工作階段符記傳遞至 Autocomplete (新版) 呼叫後的 Place Details (新版) 呼叫。詳情請參閱「工作階段符記」。

  如要設定工作階段權杖參數，請在建構 FetchPlaceRequest 物件時呼叫 setSessionToken() 方法。

Place Details 範例

以下範例會要求紐約市帝國大廈的 ID、DISPLAY_NAME 和 FORMATTED_ADDRESS 欄位。

// Define a place ID.
final String placeId = "ChIJaXQRs6lZwokRY6EFpJnhNNE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);