Place Details

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

地點詳細資訊

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

• 並呼叫 GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:。請參閱取得目前地點指南。
• 呼叫 GMSPlacesClient fetchPlaceFromPlaceID:，並傳遞 GMSPlaceField、地點 ID 和回呼方法。針對 Place Details 要求，如果您未在要求中指定至少一個欄位，或者您在要求中省略 fields 參數，則系統會傳回所有可能的欄位，並據此向您收費。請參閱依 ID 取得地點指南。

要求地點時，您必須指定要傳回的地點資料類型。為此，請傳遞 GMSPlaceField，指定要傳回的資料類型。由於這一點會影響每項要求的費用，因此這是相當重要的考量因素。

由於地點資料結果不得留空，因此只有傳回含有資料的地點結果 (例如，如果要求的地點沒有相片，則結果不會顯示 photos 欄位)。

下列範例傳送兩個欄位值的清單，以指定要求傳回的資料：

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

      // Specify the place data types to return.
      let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))!
  

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

      // Specify the place data types to return.
      GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
  

進一步瞭解地點欄位。如要進一步瞭解地點資料要求的計費方式，請參閱「用量與計費」一文。

GMSPlace 類別可包含下列地點資料：

• name - 地點名稱。
• placeID：地點的文字 ID。請在本頁的其餘部分進一步瞭解地點 ID。
• coordinate：地點的地理位置，以經緯度座標指定。
• phoneNumber - 地點的電話號碼 (國際格式)。
• formattedAddress：使用者能夠理解這個位置的地址。

  這個地址通常等於郵寄地址。請注意，由於授權上的限制，部分國家/地區 (例如英國) 不允許散布真實的郵寄地址。

  理論上，格式化地址是由一或多個「地址元件」組成。舉例來說，「111 8th Avenue, New York, NY」這個地址包含以下元件：「111」(門牌號碼)、「8th Avenue」(路名)、「New York」(城市) 和「NY」(美國州名)。

  請勿以程式輔助方式剖析格式化地址。建議您改用個別地址元件，API 回應除了包含格式化地址欄位之外，也會包含這些元件。

• openingHours - 地點的營業時間 (以 GMSOpeningHours 表示)。呼叫 GMSOpeningHours.weekdayText 以取得本週每日營業時間的本地化字串清單。呼叫 GMSOpeningHours.Periods 會傳回 GMSPeriod 清單，其中含有更詳細的資訊，相當於 weekdayText 提供的資料。注意：如果地點一律開啟，時間範圍會以星期日午夜表示，且 closeEvent 為空值。

• addressComponents：GMSAddressComponent 物件的陣列，代表地點地址的元件。這些元件是用來擷取與地點地址相關的結構化資訊，例如尋找特定地點的城市。請勿使用這些元件進行地址格式設定；請改用提供本地化格式地址的 formattedAddress 屬性。

  請注意以下 addressComponents 陣列的事實：

  • 地址元件的陣列可包含比 formattedAddress 更多的元件。
  • 除了 formattedAddress 中的實體以外，陣列中不一定會包含含有地址的所有政治實體。
  • 但不保證格式在要求之間會保持不變。具體來說，addressComponents 的數量會因要求的位址而不同，且可能會隨時間變更。元件可以變更陣列中的位置。元件類型也可能會變更。後續回應中可能會遺漏特定元件。
• userRatingsTotal - 代表地點評分有多少評論。

GMSPlace 類別包含下列成員函式：

• isOpen 會根據 openingHours 和 UTCOffsetMinutes 以及目前的日期與時間，計算出特定時間是否營業。
• isOpenAtDate 會根據 openingHours 和 UTCOffsetMinutes 以及目前的日期與時間，計算特定日期是否營業。

使用這些函式來取得開放時間和/或日期時，原始 fetchPlaceFromPlaceID: 或 findPlaceLikelihoodsFromUserLocationWithPlaceFields: 要求必須同時指定 GMSPlaceFieldOpeningHours 和 GMSPlaceFieldUTCOffsetMinutes 欄位。如果缺少其中一個欄位，產生的 GMSPlace 物件將不會包含開始時間或日期，且呼叫會傳回 GMSPlaceOpenStatusUnknown。為確保正確結果，請在原始地點要求中要求 GMSPlaceFieldBusinessStatus 和 GMSPlaceFieldUTCOffsetMinutes 欄位。如果未要求，系統會假設商家已營運。

如要瞭解如何搭配 isOpen 使用 Place Details，請參閱這部影片。

依 ID 取得地點

地點 ID 是用來識別特定地點的文字 ID，在 Places SDK for iOS 中，您可以從 GMSPlace 物件中擷取地點 ID。您可以儲存地點 ID，用來再次擷取 GMSPlace 物件。

如要依 ID 取得地點，請呼叫 GMSPlacesClient fetchPlaceFromPlaceID: 並傳遞下列參數：

• 包含地點 ID 的字串。
• 一或多個 GMSPlaceField，指定要傳回的資料類型。
• 呼叫呼叫時，用於完成自動完成查詢。否則，請傳遞 nil。
• 處理結果的 GMSPlaceResultCallback。

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

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

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

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

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

在應用程式中顯示歸因

當應用程式顯示從 GMSPlacesClient lookUpPlaceID:callback: 取得的資訊時，應用程式也必須顯示出處。請參閱歸因說明文件。

進一步瞭解地點 ID

Places SDK for iOS 使用的地點 ID 與 Places API、Places SDK for Android 及其他 Google API 中的 ID 相同。

每個地點 ID 只能參照一個地點，但一個地點可包含多個地點 ID。

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

透過指定地點 ID 要求地點，您即可確保會在回應中一律收到相同地點 (如果地點仍然存在)。但請注意，回應可能包含的地點 ID 與要求中的地點 ID 不同。

詳情請參閱地點 ID 總覽。