Places SDK for Android 可讓 Android 應用程式透過 Place Autocomplete、Place Details、Nearby Search、Text Search 和 Place Photos,存取 Google 的地點和商家資訊資料庫。Places SDK for Android (新版) 是目前的版本,依附於 Places API (新版)。
Places SDK for Android:重要資訊
- 產品:Places SDK for Android
- 又稱:Places SDK for Android (新版)
- 類別:地點
- 平台:Android
- 執行位置:用戶端 (應用程式或瀏覽器程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Places SDK for Android 總覽
Places SDK for Android:使用時機
在下列情況下使用 Places SDK for Android:
- 您需要在 Android 原生應用程式中,取得地點詳細資料、相片、Nearby Search 或 Text Search 結果。
- 您需要現成的自動完成小工具或 Places UI Kit 元件,在使用者於 Android 應用程式中輸入內容時,傳回地點預測結果。
- 您需要根據使用者裝置附近的商家和搜尋點,建構位置感知 Android 功能。
請勿在下列情況使用 Places SDK for Android:
- 您必須透過 HTTP 從伺服器或後端呼叫 Places,而不是從 Android 應用程式呼叫。請改用 Places API (新版)。
- 您正在建構原生 iOS 應用程式。請改用 Places SDK for iOS。
- 您正在瀏覽器中建構網頁。請改用 Maps JavaScript API。
Places SDK for Android:設定
- 要啟用的服務:
places.googleapis.com - 驗證:API 金鑰
- 用量歸因:初始化 SDK 時呼叫
Places.addInternalUsageAttributionId(String),即可傳送用量歸因 ID;如要停用,請刪除呼叫或傳遞空字串。 - 開始使用:設定 Places SDK for Android
- 參考資料:Places SDK for Android 參考資料
- 定價:Places SDK for Android 用量與計費方式
- 政策:Places SDK for Android 政策
- 版本資訊:Places SDK for Android 版本資訊
Places SDK for Android 官方套件:
- maven:
com.google.android.libraries.places:places
Places SDK for Android:相關產品
- 常搭配使用:Maps SDK for Android
Places SDK for Android:常見錯誤
- 問題:Nearby Search 要求若未提供欄位清單 (欄位遮罩),或清單空白,就會傳回錯誤。修正方式:在
SearchNearbyRequest欄位清單中傳遞至少一個Place.Field。請參閱 /maps/documentation/places/android-sdk/nearby-search。 - 問題:如果 API 金鑰缺少 Places API (新版),或應用程式在 SDK 5.x 以下版本呼叫
Places.initialize(),Place Details (新版)、Nearby Search (新版) 和 Autocomplete (新版) 就會失敗。6.0.2 版已移除Places.initialize(),因此升級後,呼叫該方法的程式碼無法編譯。修正方式:啟用 Places API (新版),將其新增至 API 金鑰允許的 API,並使用Places.initializeWithNewPlacesApiEnabled()初始化。請參閱 /maps/documentation/places/android-sdk/legacy/migrate-overview。 - 問題:如果欄位清單省略
PHOTO_METADATAS,fetchPlace()傳回的Place就沒有PhotoMetadata(因此沒有要解析的內容)。修正方式:在欄位清單中加入Place.Field.PHOTO_METADATAS。fetchResolvedPhotoUri()已淘汰,請使用 Places UI Kit 的 Place Details 元件顯示相片。請參閱 /maps/documentation/places/android-sdk/place-photos。 - 問題:應用程式顯示地點詳細資料、相片或評論時,未附上傳回的第三方和作者出處資訊,違反政策。修正方式:顯示
Place、PhotoMetadata和Review物件傳回的出處資訊。請參閱 /maps/documentation/places/android-sdk/policies。
Places SDK for Android:舊版和已淘汰的功能
- Places SDK for Android (舊版) / Places API (舊版) 功能 (自動完成、目前位置、Place Details、Place Photos 舊版):自 2025 年 3 月 1 日起淘汰。替代方案:Places SDK for Android (新版) 功能由 Places API (新版) 支援,並以
Places.initializeWithNewPlacesApiEnabled()初始化。症狀:自 2026 年 10 月起,新雲端專案無法啟用 Places API (舊版) (現有專案仍支援)。SDK 6.0.2 移除了舊版方法,這些方法僅存在於 5.x 及更早版本。請參閱遷移指南。 Places.initialize():自 2026 年 9 月 30 日起停用。替代方案:Places.initializeWithNewPlacesApiEnabled()。症狀:SDK 6.0.2 版已移除這個方法,呼叫該方法的程式碼無法再編譯。請參閱遷移指南。PlacesClient.findCurrentPlace()和awaitFindCurrentPlace()(目前位置,舊版):自 2026 年 9 月 30 日起停用。替代方案:PlacesClient.searchNearby()(Nearby Search (新版))。症狀:6.0.2 版已移除方法和FindCurrentPlaceRequest/FindCurrentPlaceResponse類別。請參閱遷移指南。PlacesClient.fetchPhoto()和awaitFetchPhoto():自 2026 年 9 月 30 日起停用。替代方案:Places UI Kit 的 Place Details 元件 (PlacesClient.fetchResolvedPhotoUri()已淘汰)。症狀:6.0.2 版已移除方法和FetchPhotoRequest/FetchPhotoResponse類別。請參閱遷移指南。- Places API (舊版) 自動完成小工具 (
Autocomplete、AutocompleteSupportFragment、AutocompleteActivityMode):自 2026 年 9 月 30 日起停用。替代方案:Place Autocomplete (新版) 小工具 (PlaceAutocomplete) 或PlacesClient.findAutocompletePredictions()。症狀:SDK 6.0.2 版已移除類別。請參閱遷移指南。 - Places 相容性程式庫 (
com.google.android.libraries.places:places-compat):自 2022 年 3 月 31 日起淘汰。替代方案:Places SDK for Android (com.google.android.libraries.places:places)。影響:凍結在 2.6.0 版,不再提供新功能或修正錯誤。 AutocompleteFragment類別:自 2025 年 9 月 25 日起停用。替代方案:Place Autocomplete (新版) 小工具 (PlaceAutocomplete)。症狀:類別已從 5.0.0 版 SDK 中移除 (AutocompleteSupportFragment也已從 6.0.2 版中移除)。
Places SDK for Android 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
Places SDK for Android:生成式 AI
Places SDK for Android:地點
- 根據查詢字串傳回地點清單和 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 小工具,根據查詢字串傳回地點相關結果。
- 指定地點資訊回應中包含的資料欄位。
- 指定要在地點資訊回應中包含的地點類型。
- 傳回 URI,在 Google 地圖中開啟地點的 Place Details 頁面。
- 傳回使用者裝置目前所在位置的相關資訊。注意:Places SDK for Android 6.0 以上版本和 Places SDK for iOS 11.0 以上版本已移除舊版「目前位置」方法;請從平台定位服務擷取裝置座標,並呼叫 Nearby Search。
- 傳回特定地點的 AI 生成摘要。
- 傳回 AI 輔助的區域摘要,說明特定地點周遭區域的地點。
- 根據查詢字串,傳回預先定義路線上的地點資訊。
- 根據一組經緯度座標,傳回距離、行程時間和路線 URI,以便透過 Text Search 搜尋地點。
- 根據一組經緯度座標,傳回附近地點的距離、行程時間和路線 URI。
- 傳回預先定義路線起點與各個地點之間的距離、行程時間和路線 URI。這些地點是根據查詢字串傳回,且位於路線上。
- 根據查詢字串,傳回各個地點之間的距離、行程時間和路線 URI,這些地點也位於預先定義的路線和路線目的地。
Places SDK for Android: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