Place Details (最新)

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

Places SDK for iOS (新版) 可為您的應用程式提供豐富的資訊 地點的相關資訊，包括地點的名稱和地址、 指定經緯度座標的位置，以及地點類型 (例如 例如夜店、寵物店、博物館等如要存取這項資訊 特定地點時，您可以使用地點 ID，這是能明確定義 識別地點。

取得 Place Details

GMSPlace敬上 類別包含特定地點的相關資訊，包括所有顯示在 地點資料欄位 (新)。取得 GMSPlace敬上 方法是呼叫 GMSPlacesClient fetchPlaceWithRequest:, 傳遞 GMSFetchPlaceRequest 物件 類型的回呼方法 GMSPlaceResultCallback。

GMSFetchPlaceRequest 物件會指定：

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

提出 Place Details 要求

本範例會透過 ID 取得地點，並傳送下列參數：

  • ChIJV4k8_9UodTERU5KXbkYpSYs 的地點 ID。
  • 指定傳回地點名稱和網站網址的欄位清單。
  • 處理結果的 GMSPlaceResultCallback。

API 會叫用指定的回呼方法，並傳入 GMSPlace敬上 物件。如果找不到地點，則地點物件為「nil」。

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 return.
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);
  }
}];

Places Swift SDK for iOS (預先發布版)

// 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
}

Place Details 回應

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

取得營業狀態

GMSPlacesClient 物件包含 isOpenWithRequest (Swiftt 中的 isOpenRequest，以及 GooglePlacesSwift 中的 isPlaceOpenRequest) 成員函式，可根據呼叫中指定的時間傳回回應，指出該地點目前是否營業。

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

  • GMSPlace 物件，或是指定地點 ID 的字串。如要進一步瞭解如何運用必填欄位建立 Place 物件，請參閱「Place Details」。
  • 選用的 NSDate (Obj-C) 或 Date (Swift) 物件，用於指定要查看的時間。如果您未指定時間，系統會採用預設值。
  • 處理回應的 GMSPlaceOpenStatusResponseCallback 方法。
    • &gt;
，瞭解如何調查及移除這項存取權。

使用 GMSPlaceIsOpenWithRequest 方法時，您必須在 GMSPlace 物件中設定下列欄位：

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 則回應

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

語言 值開啟時的價值 關閉後的價值 狀態不明時傳回的值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (預先發布版) true false nil

「isOpenWithRequest」的帳單

  • GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位是依據 Basic Data SKU 計費。其餘的「營業時間」則會計入 Place Details (進階) SKU 下方。
  • 如果 GMSPlace 物件「已經」有先前要求中的這些欄位，系統不會再次收費。

範例：發出 GMSPlaceIsOpenWithRequest 要求

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

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
            }
          }];

GooglePlacesSwift

          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
          }

必要參數

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

地點 ID

Places SDK for iOS 中使用的地點 ID 是 與 Places API、Places SDK for Android 中使用的 ID 和其他 Google API每個地點 ID 只能代表一個地點，但一個地點可以有多個地點 多個地點 ID

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

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

欄位清單

要求 Place Details 時，您必須指定要用於 傳回地點的 GMSPlace 物件，做為欄位遮罩。如何定義欄位遮罩 傳送值的陣列 GMSPlaceProperty 至 GMSFetchPlaceRequest 物件 欄位遮蓋是不錯的設計做法，確保您不會要求不必要的資料。 有助於避免不必要的處理時間和帳單費用。

指定下列一或多個欄位：

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

    GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

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

    GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

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

    GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

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

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

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

以下範例傳送 欄位值 ，指出要求傳回的 GMSPlace 物件包含 name 和 placeID 欄位：

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

Places Swift SDK for iOS (預先發布版)

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

選用參數

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

regionCode

用於設定回應格式的區碼，以 也就是雙字元 CLDR 代碼值。這個參數可能會造成偏誤 相關的更多內容沒有預設值。

如果回覆地址欄位的國家/地區名稱與 區碼，則地址中略過國家/地區代碼。

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

sessionToken

工作階段符記是使用者產生的字串，可追蹤自動完成功能 (新) 呼叫做為「工作階段」。Autocomplete (New) 會使用工作階段符記，將使用者自動完成搜尋的查詢和地點選取階段歸入不同的工作階段，以用於計費。工作階段符記會傳送至 Place Details (新) 呼叫。若需更多資訊，請參閲 工作階段符記。

在應用程式中顯示作者資訊

應用程式顯示 GMSPlacesClient、 (例如相片和評論)，應用程式也必須顯示必要的作者資訊。

例如 GMSPlacesClient 物件的 reviews 屬性 包含一個最多五個的陣列 GMSPlaceReview敬上 如需儲存大量結構化物件 建議使用 Cloud Bigtable每個 GMSPlaceReview 物件都可以包含作者資訊以及作者作者資訊。 如果您在應用程式中顯示評論，則必須一併顯示作者資訊或作者。 出處。

詳情請參閱 作者資訊。