本頁面由 Cloud Translation API 翻譯而成。

Place Details (最新)

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

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

iOS 版 Places SDK (新版) 可為應用程式提供豐富的地點資訊，包括地點名稱和地址、以經緯度座標表示的地理位置、地點類型 (例如夜店、寵物店、博物館) 等。如要存取特定地點的這項資訊，可以使用地點 ID。地點 ID 是用來識別特定地點的穩定 ID。

取得 Place Details

GMSPlace 類別包含特定地點的相關資訊，包括「地點資料欄位 (新版)」中顯示的所有資料欄位。呼叫 GMSPlacesClient fetchPlaceWithRequest:，傳遞 GMSFetchPlaceRequest 物件和 GMSPlaceResultCallback 類型的回呼方法，即可取得 GMSPlace 物件。

GMSFetchPlaceRequest 物件會指定：

(必要) 地點 ID，這是 Google 地方資訊資料庫和 Google 地圖中地點的專屬 ID。
(必填) GMSPlace 物件中要傳回的欄位清單，也稱為欄位遮罩，如 GMSPlaceProperty 所定義。如果您未在欄位清單中指定至少一個欄位，或是省略欄位清單，呼叫作業就會傳回錯誤。
(選用) 用於格式化回應的區域代碼。
(選用) 用於結束 Autocomplete (New) 工作階段的工作階段符記。

提出 Place Details 要求

這個範例會傳遞下列參數，依 ID 取得地點：

「ChIJV4k8_9UodTERU5KXbkYpSYs」的地點 ID。
欄位清單，指定要傳回地點名稱和網站網址。
用來處理結果的 GMSPlaceResultCallback。

API 會叫用指定的回呼方法，並傳入 GMSPlace 物件。如果找不到地點，地點物件會是 nil。

Places Swift SDK

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to retur<n.
NSArray>NSString * *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

Place Details 回應

Place Details 會傳回 GMSPlace 物件，內含地點的詳細資料。只有欄位清單中指定的欄位會填入 GMSPlace 物件。

注意： 回應 GMSPlace 物件的欄位不得為空白。舉例來說，如果欄位清單包含 GMSPlacePropertyPhotos，要求回應中的 photos 欄位，但回應中的 photos 欄位為空白，則回應 GMSPlace 物件會省略該欄位。

取得營業狀態

GMSPlacesClient 物件包含名為 isOpenWithRequest 的成員函式 (在 Swift 中為 isOpenRequest，在 GooglePlacesSwift 中為 isPlaceOpenRequest)，會根據呼叫中指定的時間傳回回應，指出地點目前是否營業。

注意：已淘汰的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函式可能不準確，不適合與 Places API (新版) 搭配使用。

這個方法會採用 GMSPlaceIsOpenWithRequest 類型的單一引數，其中包含：

GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何使用必要欄位建立 Place 物件，請參閱「地點詳細資料」。

注意：Place 物件必須包含有效的地點 ID。
選用的 NSDate (Obj-C) 或 Date (Swift) 物件，用於指定要檢查的時間。如未指定時間，則預設為現在。
用來處理回應的 GMSPlaceOpenStatusResponseCallback 方法。

GMSPlaceIsOpenWithRequest 方法需要在 GMSPlace 物件中設定下列欄位：

GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours

如果 Place 物件中未提供這些欄位，或是您傳遞地點 ID，這個方法會使用 GMSPlacesClient GMSFetchPlaceRequest: 擷取這些欄位。

`isOpenWithRequest` 則回應

isOpenWithRequest 會傳回 GMSPlaceIsOpenResponse 物件，其中包含名為 status 的布林值，指出商家是營業中、已關閉，還是狀態不明。

語言	開啟時的值	關閉時的值	狀態不明時的值
Places Swift	`true`	`false`	`nil`
Swift	`.open`	`.closed`	`.unknown`
Objective-C	`GMSPlaceOpenStatusOpen`	`GMSPlaceOpenStatusClosed`	`GMSPlaceOpenStatusUnknown`

「`isOpenWithRequest`」的帳單

GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位會依基本資料 SKU 收費。其餘營業時間則會依地點詳細資料企業 SKU 計費。
如果您的 GMSPlace 物件已透過先前的要求取得這些欄位，系統不會再次收費。
警告：如果 GMSPlace 物件沒有這些欄位，系統會再次收取 Basic Data SKU 的費用。其餘營業時間則會以地點詳細資料企業 SKU 計費。如果專案會使用 isOpenWithRequest，建議您務必擷取必要地點詳細資料。

範例：提出 `GMSPlaceIsOpenWithRequest` 要求

以下範例說明如何在現有的 GMSPlace 物件中初始化 GMSPlaceIsOpenWithRequest。

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

必要參數

使用 GMSFetchPlaceRequest 物件指定必要參數。

地點 ID

Places SDK for iOS 中使用的地點 ID，與 Places API、Places SDK for Android 和其他 Google API 中使用的 ID 相同。每個地點 ID 只能參照一個地點，但單一地點可有多個地點 ID。

在某些情況下，地點可能會獲得新的地點 ID。舉例來說，如果商家搬遷到新址，就可能發生這種情況。

指定地點 ID 要求地點時，您可以放心，回覆一律會提供相同地點 (如果該地點仍存在)。但請注意，回應中可能包含與要求中不同的地點 ID。

欄位清單

要求地點詳細資料時，您必須在地點的 GMSPlace 物件中指定要傳回的資料，做為欄位遮罩。如要定義欄位遮罩，請將 GMSPlaceProperty 中的值陣列傳遞至 GMSFetchPlaceRequest 物件。欄位遮蓋是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

指定下列一或多個欄位：

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

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

GMSPlacePropertyAddressComponents
GMSPlacePropertyFormattedAddress
GMSPlacePropertyCoordinate
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyViewport
下列欄位會觸發 Place Details Pro SKU：

GMSPlacePropertyBusinessStatus
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyName
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyWheelchairAccessibleEntrance
下列欄位會觸發 Place Details Pro SKU：

GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite
下列欄位會觸發 Place Details Enterprise SKU：

GMSPlacePropertyCurbsidePickup
GMSPlacePropertyDelivery
GMSPlacePropertyDineIn
GMSPlacePropertyEditorialSummary
GMSPlacePropertyReservable
GMSPlacePropertyReviews
GMSPlacePropertyServesBeer
GMSPlacePropertyServesBreakfast
GMSPlacePropertyServesBrunch
GMSPlacePropertyServesDinner
GMSPlacePropertyServesLunch
GMSPlacePropertyServesVegetarianFood
GMSPlacePropertyServesWine
GMSPlacePropertyTakeout

以下範例會傳遞兩個欄位值的清單，指定要求傳回的 GMSPlace 物件包含 name 和 placeID 欄位：

Places Swift SDK

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

Swift

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

Objective-C

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

選用參數

使用 GMSFetchPlaceRequest 物件指定選用參數。

regionCode

用於格式化回應的區域代碼，指定為兩個字元的 CLDR 代碼值。這個參數也可能對搜尋結果造成偏誤。沒有預設值。

如果回應中地址欄位的國家/地區名稱與區域代碼相符，地址會省略國家/地區代碼。

大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(嚴格來說，這是「大不列顛及北愛爾蘭聯合王國」的代碼)。視適用法律而定，這項參數可能會影響結果。

sessionToken

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

在應用程式中顯示出處資訊

如果應用程式會顯示以 GMSPlacesClient 取得的資訊 (例如相片和評論)，則也須顯示必要的出處資訊。

舉例來說，GMSPlacesClient 物件的 reviews 屬性最多可包含五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件都可以包含出處和作者出處。如果應用程式會顯示評論，則也須顯示任何出處或作者出處資訊。

詳情請參閱出處資訊說明文件。

Place Details (最新) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

取得 Place Details

提出 Place Details 要求

Places Swift SDK

Swift

Objective-C

Place Details 回應

取得營業狀態

isOpenWithRequest 則回應

「isOpenWithRequest」的帳單

範例：提出 GMSPlaceIsOpenWithRequest 要求

Places Swift SDK

Swift

Objective-C

必要參數

地點 ID

欄位清單

Places Swift SDK

Swift

Objective-C

選用參數

regionCode

sessionToken

在應用程式中顯示出處資訊

Place Details (最新)

`isOpenWithRequest` 則回應

「`isOpenWithRequest`」的帳單

範例：提出 `GMSPlaceIsOpenWithRequest` 要求