Place Details (最新)

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

歐洲經濟區 (EEA) 開發人員

如要取得特定商家或景點的詳細資料，請使用地點 ID 提出 Place Details (New) 要求。Place Details (New) 會傳回指定地點的更完整資訊，例如完整地址、電話號碼、使用者評分和評論。

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

Place Details (New) 要求

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

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

Place Details (新版) 回應

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

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

必要參數

FetchPlaceRequest 的必要參數如下：

  • 地點 ID

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

  • 欄位清單

    要求地點時，您必須指定要傳回的地點資料。如要這麼做，請傳遞 Place.Field 值清單，指定要傳回的資料。回應中沒有預設的傳回欄位清單。

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

    指定下列一或多個欄位：

    • 下列欄位會觸發「Place Details Essentials IDs Only」SKU：

      Place.Field.ID
      Place.Field.PHOTO_METADATAS
      Place.Field.RESOURCE_NAME

    • 下列欄位會觸發 Place Details Essentials SKU：

      Place.Field.ADDRESS_COMPONENTS
      ADR_FORMAT_ADDRESS
      Place.Field.FORMATTED_ADDRESS*
          * 請改用這個函式，不要使用 Place.Field.ADDRESS (已淘汰)。
      Place.Field.LOCATION* 請改用 Place.Field.LAT_LNG (已淘汰)。

      Place.Field.PLUS_CODE
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.TYPES
      Place.Field.VIEWPORT

    • 下列欄位會觸發 Place Details Pro SKU：

      Place.Field.ACCESSIBILITY_OPTIONS*
          * 請改用這個函式，不要使用 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (已淘汰)。
      Place.Field.BUSINESS_STATUS
      Place.Field.DISPLAY_NAME*
          * 請改用這個函式，因為 Place.Field.NAME 已淘汰。
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * 請改用這個函式，不要使用 Place.Field.ICON_URL (已淘汰)。
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SUB_DESTINATIONS
      Place.Field.UTC_OFFSET

    • 下列欄位會觸發 Place Details Enterprise SKU：

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * 請改用這個函式，因為 Place.Field.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.USER_RATINGS_TOTAL 已淘汰。
      Place.Field.WEBSITE_URI

    • 下列欄位會觸發 Place Details Enterprise Plus 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

選用參數

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);