Place Details

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

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

地點詳細資訊

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

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

警告：如果您沒有在要求中指定至少一個欄位，或是在要求中省略 fields 參數，系統會傳回「所有」可能的欄位，並據此向您收費。這項設定僅適用於 Place Details 要求。

要求地點時，您必須指定要傳回哪些類型的地點資料。如要這麼做，請傳遞 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);

GMSPlaceFieldTakeout、GMSPlaceFieldDelivery、GMSPlaceFieldDineIn、GMSPlaceFieldCurbsidePickup、GMSPlaceFieldPhoneNumber、GMSPlaceFieldWebsite、GMSPlaceFieldOpeningHours 和 GMSPlaceFieldAddressComponents 不支援 GMSPlaceLikelihoodList 地點物件。

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

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 欄位。如果未提出要求，系統會假設商家正在營業。

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，並在日後使用該 ID 擷取 GMSPlace 物件。

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

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

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

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: 取得的資訊，則也須顯示出處資訊。請參閱歸屬說明文件。

進一步瞭解 Place ID

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

每個地點 ID 只能指一個地點，但一個地點可有多個地點 ID。

有些情況可能會導致地點取得新地點 ID。舉例來說，如果商家搬遷至新地點，就可能發生這種情況。

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

詳情請參閱地點 ID 總覽。