Place Details

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

地點詳細資訊

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

要求地點時，您必須指定要傳回的地點資料類型。如要這麼做，請傳遞 GMSPlaceField，指定要傳回的資料類型。這項考量非常重要，因為這會影響每項要求的費用。

地點資料結果不可空白，因此系統只會傳回含有資料的地點結果 (例如，如果要求的地點沒有相片，photos 欄位就不會顯示在結果中)。

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

Swift

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

Objective-C

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

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

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

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

  • name：地點的名稱。
  • editorialSummary：提供地點說明。
  • 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 為空值。
  • currentOpeningHours 和 secondaryOpeningHours：這些欄位會反映某地點的假日和臨時時間表變更。

  • addressComponents：GMSAddressComponent 物件陣列，代表地點地址的元件。這些元件可用於擷取地點地址的結構化資訊，例如找出地點所在的城市。請勿使用這些元件設定地址格式，而應使用 formattedAddress 屬性，該屬性會提供本地化的格式化地址。

    addressComponents 陣列的注意事項如下：

    • 地址元件陣列包含的元件可能比 formattedAddress 更多。
    • 除了 formattedAddress 中所含的政治實體以外，這個陣列不一定會納入內含地址的所有政治實體。
    • 兩次要求之間的回應格式不一定相同。特別是，addressComponents 的數量會因要求的地址而異，對於同一個地址，數量也可能會隨時間改變。元件在陣列中的位置可能會變更。 元件類型也可能會變更。後續回應中可能會缺少特定元件。
  • userRatingsTotal：代表地點評分的評論數量。

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

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

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

    如要瞭解如何搭配 Place Details 使用 isOpen，請觀看如何取得營業時間影片。

取得特殊營業時間

一般營業時間是透過 openingHours 取得，currentOpeningHours 和 secondaryOpeningHours 則支援假日和臨時時間表變更。 如有需要，可以篩選並顯示這些特殊日期的例外營業時間。

Swift

    func examineOpeningHours(place: GMSPlace) {

      // Check if the current opening hours contains a special day that has exceptional hours
      guard let currentOpeningHours = place.currentOpeningHours else { return }
      if let specialDays = currentOpeningHours.specialDays {
        guard !specialDays.isEmpty else { return }
        if let specialDay = specialDays.filter { $0.isExceptional }.first  {
          // Indicate exceptional hours
        }
      }

      // Check if current opening hours contains a truncated time period
      let periods = currentOpeningHours.periods

      if !periods.isEmpty {
        for period in periods {
          let open = period.open
          let close = period.close

          if let open = open {
            let date = open.date

            if open.isTruncated {
              // Indicate truncated time period
            }
          }
        }
      }

      // Check if the place's secondary opening hours indicate when delivery is available
      let secondaryOpeningHours = place.secondaryOpeningHours
      guard let hoursType = secondaryOpeningHours.first?.hoursType else {
      return
      }

      if (hoursType == GMSPlaceHoursTypeDelivery) {
        // Indicate hours where delivery is available
      }
  }

Objective-C

- (void)examineOpeningHours:(GMSPlace *) place {

    // Check if the current opening hours contains a special day that has exceptional hours
    GMSOpeningHours *currentOpeningHours = place.currentOpeningHours;
    if (currentOpeningHours != nil) {
      NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays;
      if ([specialDays count] != 0) {
        for (GMSPlaceSpecialDay *specialDay in specialDays) {
          NSDate *date = specialDay.date;
          if ([specialDay isExceptional]) {
            // Indicate exceptional hours
          }
        }
      }
    }

    // Check if current opening hours contains a truncated time period
    NSArray <GMSPeriod *> * periods = currentOpeningHours.periods;

    if ([periods count] != 0) {
      for (GMSPeriod * period in periods) {
        GMSTimeOfWeek *open = period.open;
        GMSTimeOfWeek *close = period.close;

        if (open) {
          if ([open isTruncated]) {
            // Indicate truncated time period
          }
        }
      }
    }

    // Check if the place's secondary opening hours indicate when delivery is available
    GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours;
    GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType;

    if (hoursType == GMSPlaceHoursTypeDelivery) {
      // Indicate hours where delivery is available
    }
}

依 ID 取得地點

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

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

  • 包含地點 ID 的字串。
  • 一或多個 GMSPlaceField，指定要傳回的資料類型。
  • 如果呼叫是為了結束自動完成查詢，則為工作階段符記。否則請傳遞 nil。
  • 用於處理結果的 GMSPlaceResultCallback。

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

Places Swift SDK for iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Swift

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

Objective-C

// 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 總覽。