Places SDK for Android 快速参考

借助 Places SDK for Android,Android 应用可以通过地点自动补全、地点详情、附近搜索、文本搜索和地点照片功能访问 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 应用中获取地点详情、照片、附近搜索或文本搜索结果。
  • 您需要一个现成的自动补全 widget 或 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:常见错误

  • 问题:如果“附近搜索”请求不包含字段列表(字段掩码)或字段列表为空,则会返回错误。解决方法:在 SearchNearbyRequest 字段列表中至少传递一个 Place.Field。请参阅 /maps/documentation/places/android-sdk/nearby-search。
  • 问题:如果 API 密钥缺少 Places API(新版),或者在 SDK 5.x 及更早版本中应用调用 Places.initialize(),则地点详情(新版)、附近搜索(新版)和自动补全(新版)会失败。版本 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 地点详情组件来显示照片。请参阅 /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(旧版)功能(自动补全、当前地点、地点详情、地点照片旧版):自 2025 年 3 月 1 日起弃用。替代方案:由 Places API(新版)提供支持的 Places SDK for Android(新版)功能,使用 Places.initializeWithNewPlacesApiEnabled() 进行初始化。症状:自 2026 年 10 月起,新的云项目将无法启用 Places API(旧版)(现有项目仍受支持)。SDK 6.0.2 移除了旧版方法,这些方法仅存在于 5.x 及更早版本中。请参阅迁移指南。
  • Places.initialize():自 2026 年 9 月 30 日起已停用。替换:Places.initializeWithNewPlacesApiEnabled()。症状:该方法已从 6.0.2 版 SDK 中移除;调用该方法的代码不再编译。请参阅迁移指南。
  • PlacesClient.findCurrentPlace() 和 awaitFindCurrentPlace()(当前地点,旧版):自 2026 年 9 月 30 日起停用。替代产品:PlacesClient.searchNearby()(附近搜索 [New])。症状:6.0.2 中移除了方法和 FindCurrentPlaceRequest/FindCurrentPlaceResponse 类。请参阅迁移指南。
  • PlacesClient.fetchPhoto() 和 awaitFetchPhoto():自 2026 年 9 月 30 日起停用。替代方案:Places UI Kit 地点详情组件(PlacesClient.fetchResolvedPhotoUri() 已弃用)。症状:6.0.2 中移除了方法和 FetchPhotoRequest/FetchPhotoResponse 类。请参阅迁移指南。
  • Places API(旧版)自动补全 widget(Autocomplete、AutocompleteSupportFragment、AutocompleteActivityMode):自 2026 年 9 月 30 日起停用。替代方案:地点自动补全(新版)widget (PlaceAutocomplete) 或 PlacesClient.findAutocompletePredictions()。症状:在 6.0.2 中,从 SDK 中移除了类。请参阅迁移指南。
  • Places 兼容性库 (com.google.android.libraries.places:places-compat):自 2022 年 3 月 31 日起弃用。替代产品:Places SDK for Android (com.google.android.libraries.places:places)。影响:冻结在 v2.6.0;没有新功能或问题修复。
  • AutocompleteFragment 类:自 2025-09-25 起已停用。替代项:地点自动补全(新版)微件 (PlaceAutocomplete)。症状:5.0.0 版 SDK 中移除了该类(6.0.2 版中也移除了 AutocompleteSupportFragment)。

Places SDK for Android 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Places SDK for Android:生成式 AI

Places SDK for Android:地点

Places SDK for Android:Places UI Kit

  • 对地点数据界面元素应用 CSS 样式。注意:CSS 自定义属性适用于 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 则使用主题和样式属性,以编程方式设置 Place UI Kit 视图的样式。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 使用界面元素自定义工具自定义地点数据界面元素的样式和配置。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或移动应用添加一个界面元素,用于显示特定地点的相关信息。注意:欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页中添加一个界面元素,用于根据查询字符串显示地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页添加一个界面元素,用于显示特定位置附近的地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或应用添加基本的自动补全界面元素,该元素会根据查询字符串返回 Google 地点标识符。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq