借助 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:
- 您需要通过 HTTP 从服务器或后端(而非 Android 应用)调用 Places。请改用 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:常见错误
- 问题:如果“附近搜索”请求不包含字段列表(字段掩码)或字段列表为空,则会返回错误。解决方法:在
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:地点
- 根据查询字符串返回地点列表和地点详情。
- 返回特定位置附近的地点列表和地点详情。
- 根据查询字符串返回有关地点的自动补全结果。
- 返回特定地点的详细信息。
- 返回特定地点的照片。注意:请在每张照片旁边显示其作者信息(作者姓名,链接到其个人资料 URI)。每个平台的地点政策都要求这样做,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 调整地点照片的大小。
- 返回特定地点的评分和评价。注意:在 Places API(新版)网络服务中,“地点详情”是向 https://places.googleapis.com/v1/places/{placeId} 发出的 HTTP GET 请求,其中包含 X-Goog-FieldMask(例如 rating、userRatingCount、reviews);“文本搜索”“附近搜索”和“自动补全”使用 POST。在 Android 上,将 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 传递给 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中传递 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 向网页或应用添加自动补全 widget,以便根据查询字符串返回地点相关结果。
- 指定地点信息响应中包含的数据字段。
- 指定要在地点信息响应中包含的地点类型。
- 返回用于在 Google 地图中打开某个地点的地点详情页面的 URI。
- 返回与用户设备当前所在地点相关的信息。注意:Places SDK for Android v6.0 及更高版本以及 Places SDK for iOS v11.0 及更高版本中移除了旧版“当前地点”方法;请从平台位置信息服务中检索设备坐标,然后调用“附近搜索”。
- 返回特定地点的 AI 生成的概览摘要。
- 返回 AI 赋能的区域摘要,其中描述了特定地点周围区域内的地点。
- 根据查询字符串返回位于预定义路线沿线的地点的相关信息。
- 返回从一组纬度/经度坐标到文本搜索地点的距离、行程时间和路线 URI。
- 根据一组纬度/经度坐标,返回到附近的地点 的距离、行程时间和路线 URI。
- 返回预定义路线的起点与根据查询字符串返回的每个地点(也位于该路线上)之间的距离、行程时间和路线 URI。
- 返回基于查询字符串返回的每个地点(这些地点也位于预定义路线上)与路线目的地之间的距离、行程时间和路线 URI。
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