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 的情況:
- 您正在建構原生 Android 應用程式。請改用 Places SDK for Android。
- 您正在瀏覽器中建構網頁。請改用 Maps JavaScript API。
- 您需要透過 HTTP 從伺服器或後端取得地點資料,而不是在 iOS 用戶端中取得。請改用 Places API (新版)。
Places SDK for iOS:設定
- 要啟用的服務:
places.googleapis.com - 驗證:API 金鑰
- 使用情形歸因:在
GMSPlacesClient(Objective-C/Swift) 或PlacesClient(GooglePlacesSwift) 上呼叫類別方法addInternalUsageAttributionID,即可新增使用情形歸因 ID;刪除呼叫則會停用。 - 開始使用:設定 Places SDK for iOS
- 參考資料:Places SDK for iOS 參考資料
- 定價:Places SDK for iOS 用量與計費
- 政策: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:相關產品
- 常搭配使用:Maps SDK for iOS
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),導致編譯失敗。請參閱遷移指南。 GMSAutocompleteResultsViewControllersetAutocompleteBoundsUsingNorthEastCorner:SouthWestCorner和GMSAutocompleteFetcherinitWithBounds:filter:自 2020 年 10 月 13 日起停用。替代方案:在GMSAutocompleteRequest上使用GMSAutocompleteFilter(locationBias或locationRestriction) 搭配GMSPlacesClientfetchAutocompleteSuggestionsFromRequest:callback:,或 UI 小工具的GooglePlacesSwiftplaceAutocomplete或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) 和GMSPlacesClientfetchAutocompleteSuggestionsFromRequest:callback:,或 UI 小工具的GooglePlacesSwiftplaceAutocomplete或basicPlaceAutocomplete修飾符。症狀:SDK 4.0.0 以上版本不含屬性和參數 (SDK 11.0.0 則移除GMSAutocompleteViewController和findAutocompletePredictionsFromQuery)。請參閱遷移指南。GMSPlace.openNowStatus:自 2020 年 10 月 13 日起停用。替代方案:GooglePlacesSwift中的GMSPlacesClientisOpenWithRequest: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:地點
- 根據查詢字串傳回地點清單和 Place Details。
- 傳回特定位置附近的地點和地點詳細資料清單。
- 根據查詢字串,傳回地點的自動完成結果。
- 傳回特定地點的詳細資訊。
- 傳回特定地點的相片。注意:請在相片旁顯示每張相片的作者資訊 (作者姓名,並連結至其個人資料 URI)。各平台的 Places 政策都有這項規定,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 調整地點相片大小。
- 傳回特定地點的評分和評論。注意:在 Places API (新版) Web 服務中,Place Details 是向 https://places.googleapis.com/v1/places/{placeId} 傳送的 HTTP GET 要求,並包含 X-Goog-FieldMask (例如 rating、userRatingCount、reviews);Text Search、Nearby Search 和 Autocomplete 則使用 POST。在 Android 上,將 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 傳遞至 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中傳遞 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 在網頁或應用程式中加入 Autocomplete 小工具,根據查詢字串傳回地點相關結果。
- 指定地點資訊回應中包含的資料欄位。
- 指定要在地點資訊回應中包含的地點類型。
- 傳回使用者裝置目前所在位置的相關資訊。注意:Places SDK for Android 6.0 以上版本和 Places SDK for iOS 11.0 以上版本已移除舊版「目前位置」方法;請從平台定位服務擷取裝置座標,並呼叫 Nearby Search。
- 傳回特定地點的 AI 生成摘要。
- 傳回 AI 輔助的區域摘要,說明特定地點周遭區域的地點。
- 根據查詢字串,傳回預先定義路線上的地點資訊。
- 根據一組經緯度座標,傳回距離、行程時間和路線 URI,以便透過 Text Search 搜尋地點。
- 根據一組經緯度座標,傳回附近地點的距離、行程時間和路線 URI。
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