Places SDK for Android 快速參考

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:

Places SDK for Android:設定

Places SDK for Android 官方套件:

  • maven:com.google.android.libraries.places:places

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:地點

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