iOS 適用的 Places SDK 可為應用程式提供豐富的地點資訊,包括地點名稱和地址、以經緯度座標指定的地理位置、地點類型 (例如夜店、寵物店、博物館) 等。如要存取特定地點的這項資訊,可以使用地點 ID。地點 ID 是用來識別特定地點的穩定 ID。
地點詳細資訊
GMSPlace
類別提供特定地點的相關資訊。您可以透過下列方式取得 GMSPlace
物件:
- 呼叫
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
。請參閱取得目前地點指南。 - 呼叫
GMSPlacesClient fetchPlaceFromPlaceID:
,並傳遞GMSPlaceField
、地點 ID 和回呼方法。如果是 Place Details 要求,如果您沒有在要求中指定至少一個欄位,或是在要求中省略fields
參數,系統會傳回「所有」可能的欄位,並據此向您收費。請參閱依 ID 取得地點指南。
要求地點時,您必須指定要傳回的地點資料類型。如要這麼做,請傳遞 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
欄位。如未要求,系統會假設商家正常營運。
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。
iOS 版 Places Swift SDK
// 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 總覽。