Places SDK for iOS 可為您的應用程式提供豐富的地點相關資訊，包括地點的名稱和地址、以經緯度座標指定的地理位置，以及地點類型 (例如夜店、寵物店、博物館等)。如要存取特定地點的這項資訊，您可以使用地點 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- 地點名稱。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。
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 不同。
詳情請參閱地點 ID 總覽。