Places SDK for iOS 快速參考

iOS 應用程式可透過 Places SDK for iOS,使用 Place Details、Place Photos、Text Search、Nearby Search 和 Autocomplete,取得地點 (商家、搜尋點、地理位置) 相關資訊。Places API (新版) 是目前的 SDK 版本。

Places SDK for iOS:重要資訊

  • 產品:Places SDK for iOS
  • 別名:Places SDK for iOS (新版)
  • 類別:地點
  • 平台:iOS
  • 執行位置:用戶端 (應用程式或瀏覽器程式碼)
  • 推出階段:GA
  • 生命週期:有效
  • 總覽:Places SDK for iOS 總覽

Places SDK for iOS:使用時機

在下列情況下使用 Places SDK for iOS:

  • 您需要在原生 iOS 應用程式中,取得地點詳細資料、相片、Text Search 或 Nearby Search 結果。
  • 您需要在使用者於 iOS 應用程式中輸入內容時,自動完成地點名稱或地址。
  • 您想在 iOS 應用程式中使用預先建構的 Places UI Kit 元件 (Place Details、Place Search、Place Autocomplete)。

不適合使用 Places SDK for iOS 的情況:

Places SDK for iOS:設定

Places SDK for iOS 官方套件:

  • swift_package: https://github.com/googlemaps/ios-places-sdk (GooglePlaces, GooglePlacesSwift)

Places SDK for iOS:常見錯誤

  • 問題:如果 Cloud 專案未啟用 Places API (新版),或 API 金鑰的授權 API 清單未列入 Places API (新版),Places SDK for iOS (新版) 呼叫就會失敗。修正方式:啟用 Places API (新版),並將其新增至應用程式使用的 API 金鑰限制。請參閱 /maps/documentation/places/ios-sdk/legacy/migrate-overview。
  • 問題:kGMSPlacesRateLimitExceeded (-7) 表示 API 金鑰超過用量頻率限制;在已停用的 SDK 2.x 版本 (2019 年 7 月 29 日停用) 上執行的應用程式也會收到這則錯誤訊息。修正方式:在 Google Cloud 控制台中查看 Places API (新版) 的配額和用量,並更新 SDK 版本低於 3.0 的應用程式。請參閱 /maps/documentation/places/ios-sdk/reference/objc/Enums/GMSPlacesErrorCode。
  • 問題:在同一專案的不同應用程式或不同工作階段中重複使用工作階段符記,會導致自動完成工作階段計費分組中斷。修正方式:為每個自動完成工作階段產生不重複的工作階段符記 (建議使用第 4 版 UUID);每個專案的符記不得重複。請參閱 /maps/documentation/places/ios-sdk/use-session-tokens。
  • 問題:應用程式顯示地點資料,但未提供 API 傳回的出處資訊。修正方式:根據政策頁面,顯示與 Places 資料一併傳回的所有相關出處。請參閱 /maps/documentation/places/ios-sdk/overview。

Places SDK for iOS:舊版和已淘汰的功能

  • Places SDK for iOS (舊版):自 2025 年 3 月 1 日起淘汰。替代方案:Places SDK for iOS (新版) (需要 Places API (新版))。症狀:SDK 11.0.0 以上版本不支援舊版類別和方法 (例如 fetchPlaceFromPlaceID、GMSAutocompleteFetcher 和 GMSAutocompleteViewController),導致編譯失敗。請參閱遷移指南。
  • GMSAutocompleteResultsViewController setAutocompleteBoundsUsingNorthEastCorner:SouthWestCorner 和 GMSAutocompleteFetcher initWithBounds:filter:自 2020 年 10 月 13 日起停用。替代方案:在 GMSAutocompleteRequest 上使用 GMSAutocompleteFilter (locationBias 或 locationRestriction) 搭配 GMSPlacesClient fetchAutocompleteSuggestionsFromRequest:callback:,或 UI 小工具的 GooglePlacesSwift placeAutocomplete 或 basicPlaceAutocomplete 修飾符。症狀:SDK 4.0.0 以上版本不支援這些方法 (GMSAutocompleteResultsViewController 和 GMSAutocompleteFetcher 已從 SDK 11.0.0 移除)。請參閱遷移指南。
  • GMSCoordinateBounds 型自動完成邊界 (GMSAutocompleteViewController.autocompleteBounds/autocompleteBoundsMode;bounds/boundsMode 參數 findAutocompletePredictionsFromQuery 和 autocompleteQuery):已於 2020 年 10 月 13 日停用。替代方案:GMSAutocompleteRequest 搭配 GMSAutocompleteFilter (locationBias 或 locationRestriction) 和 GMSPlacesClient fetchAutocompleteSuggestionsFromRequest:callback:,或 UI 小工具的 GooglePlacesSwift placeAutocomplete 或 basicPlaceAutocomplete 修飾符。症狀:SDK 4.0.0 以上版本不含屬性和參數 (SDK 11.0.0 則移除 GMSAutocompleteViewController 和 findAutocompletePredictionsFromQuery)。請參閱遷移指南。
  • GMSPlace.openNowStatus:自 2020 年 10 月 13 日起停用。替代方案:GooglePlacesSwift 中的 GMSPlacesClient isOpenWithRequest:callback: (GMSPlaceIsOpenRequest) 或 PlacesClient.isPlaceOpen(with:)。症狀:SDK 4.0.0 以上版本沒有這個屬性。請參閱遷移指南。
  • GMSPlaceField 為 NS_ENUM:已於 2020 年 10 月 13 日停用。替代方案:GMSPlaceProperty 常數,搭配 GMSFetchPlaceRequest 和 GMSPlaceSearchByTextRequest 等要求類別,或 GooglePlacesSwift 中的 PlaceProperty。症狀:在 SDK 4.0.0 中由 NS_OPTIONS 取代 (GMSPlaceField,因為 NS_OPTIONS 屬於舊版 API,且不存在於 SDK 11.0.0 以上版本)。請參閱遷移指南。
  • Places SDK for iOS 2.7.0 版:自 2019 年 7 月 29 日起停用。替代方案:目前的 Places SDK for iOS 版本。問題:kGMSPlacesRateLimitExceeded 錯誤。

Places SDK for iOS 的用途

請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。

Places SDK for iOS:生成式 AI

Places SDK for iOS:地點

Places SDK for iOS:Places UI Kit

  • 將 CSS 樣式套用至地點資料 UI 元素。注意:CSS 自訂屬性適用於 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 則會使用主題和樣式屬性,以程式輔助方式設定 Place UI Kit 檢視區塊的樣式。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 使用 UI 元素自訂工具,自訂地點資料 UI 元素的樣式和設定。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁或行動應用程式中,新增顯示特定地點資訊的 UI 元素。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API 網路服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁中新增 UI 元素,根據查詢字串顯示地點清單。注意:網頁 (Maps JavaScript API) 和行動應用程式 (Places SDK for Android 和 Places SDK for iOS) 皆支援。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁中加入 UI 元素,顯示特定位置附近的地點清單。注意:網頁 (Maps JavaScript API) 和行動應用程式 (Places SDK for Android 和 Places SDK for iOS) 皆支援。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁或應用程式中加入基本的自動完成 UI 元素,根據查詢字串傳回 Google 地點 ID。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq