Place Details

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

地點詳細資訊

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

地點欄位

要求地點時,您必須指定要傳回的地點資料類型。為此,請傳遞 GMSPlaceField,指定要傳回的資料類型。這是非常重要的考量因素,因為這會影響每個要求的費用。由於地點資料結果不得留空,因此系統只會傳回含有資料的地點結果 (例如,如果要求的地點沒有相片,則結果不會顯示 photos 欄位)。您可以指定下列一或多個欄位:

  • GMSPlaceFieldName
  • GMSPlaceFieldPlaceID
  • GMSPlaceFieldPlusCode
  • GMSPlaceFieldBusinessStatus
  • GMSPlaceFieldCoordinate
  • GMSPlaceFieldOpeningHours
  • GMSPlaceFieldPhoneNumber
  • GMSPlaceFieldFormattedAddress
  • GMSPlaceFieldRating
  • GMSPlaceFieldPriceLevel
  • GMSPlaceFieldTypes
  • GMSPlaceFieldWebsite
  • GMSPlaceFieldViewport
  • GMSPlaceFieldAddressComponents
  • GMSPlaceFieldPhotos
  • GMSPlaceFieldUserRatingsTotal
  • GMSPlaceFieldIconImageURL
  • GMSPlaceFieldIconBackgroundColor
  • GMSPlaceFieldUTCOffsetMinutes
  • GMSPlaceFieldAll

進一步瞭解地點欄位。如要進一步瞭解地點資料要求的計費方式,請參閱用量與帳單

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

  • name - 地點名稱。
  • placeID:地點的文字 ID。請參閱本頁面的其他部分,進一步瞭解地點 ID。
  • coordinate:地點的地理位置,以經緯度座標指定。
  • businessStatus - 地點的營運狀態。可包含下列其中一個值:GMSBusinessStatusOperationalGMSBusinessStatusClosedTemporarilyGMSBusinessStatusClosedPermanentlyGMSBusinessStatusUnknown
  • phoneNumber - 地點的電話號碼 (國際格式)。
  • formattedAddress:使用者能夠理解這個位置的地址。

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

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

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

  • rating - 地點的綜合評分;以浮點值表示,傳回值介於 1.0 至 5.0 之間的值 (依據使用者匯總評論)。
  • openingHours - 地點的營業時間 (以 GMSOpeningHours 表示)。呼叫 GMSOpeningHours.weekdayText 即可取得本週每日營業時間的本地化字串清單。呼叫 GMSOpeningHours.Periods 會傳回 GMSPeriod 清單,其中含有更詳細的資訊,相當於 weekdayText 提供的資料。注意:如果地點一律開啟,時間範圍會以星期日午夜表示,closeEvent 為空值。
  • plusCode - 地點的 Plus Code 表示法。
  • priceLevel - 此地點的價格等級,以 0 (最低) 至 4 (最高) 之間的整數傳回。
  • types:用於識別這個地點的地點類型清單。這個陣列可包含多個值,也可能為空白。不需事先通知,即可導入新的值。請參閱支援的類型清單。
  • website - 地點網站的 URI (如果已知)。這是指由商家或其他與地點相關聯的實體所維護的網站。
  • attributions - 包含 NSAttributedString 的屬性,如果應用程式使用從 Places SDK for iOS 擷取的地點詳細資料,則必須向使用者顯示此屬性。如要進一步瞭解如何擷取及顯示作者資訊,請參閱歸因指南
  • addressComponentsGMSAddressComponent 物件的陣列,代表地點地址的元件。這些元件是用來擷取與地點地址相關的結構化資訊,例如用來尋找地點所在的城市。請勿使用這些元件設定地址格式;請改用提供本地化格式地址的 formattedAddress 屬性。

    請注意,以下有關 addressComponents 陣列的事實:

    • 地址元件的陣列可包含比 formattedAddress 更多的元件。
    • 除了 formattedAddress 中的實體以外,這個陣列不一定會包含含有地址的所有政治實體。
    • 但不保證會讓要求的格式保持不變。具體來說,addressComponents 的數量會因要求的位址而異,且同一個地址可能會隨時間改變。元件可以變更陣列中的位置。元件類型也可能會變更。後續回覆中可能會缺少特定元件。
  • userRatingsTotal - 代表地點評分的數量。
  • GMSPlaceFieldIconImageURL:代表地點類型的圖示網址 (PNG 格式)。
  • GMSPlaceFieldIconBackgroundColor:地點類型圖示的背景顏色。
  • UTCOffsetMinutes - 地點的時區偏移 (以分鐘為單位)。

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

  • isOpen 會根據 openingHoursUTCOffsetMinutes 以及目前的日期與時間,計算地點是否在特定時間營業。
  • isOpenAtDate 會根據 openingHoursUTCOffsetMinutes 以及目前的日期和時間,計算特定日期是否營業。
  • 使用這些函式取得開始時間和/或日期時,原始 fetchPlaceFromPlaceID:findPlaceLikelihoodsFromUserLocationWithPlaceFields: 要求必須同時指定「GMSPlaceFieldOpeningHours」和「GMSPlaceFieldUTCOffsetMinutes」欄位。如果缺少其中一個欄位,產生的 GMSPlace 物件不會包含開始時間或日期,且呼叫會傳回 GMSPlaceOpenStatusUnknown。為確保準確的結果,請在原始地點要求中要求 GMSPlaceFieldBusinessStatusGMSPlaceFieldUTCOffsetMinutes 欄位。如果未要求,系統會假設商家正在營運。

    如要瞭解如何透過 Place Details 使用 isOpen,請觀看這部影片

依 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 總覽