您的应用中可用的 Places SDK for Android 功能取决于您在应用配置中指定的 SDK 版本号(例如 3.5.0)、您在 API 密钥上启用的 API 以及初始化应用的方式。本指南介绍了版本之间的差异以及如何选择要在应用中启用哪些版本。
SDK 版本号
您在应用级 build.gradle 文件中指定的 SDK 版本号决定了您的应用是否可以访问特定版本中添加的功能。例如,自动补全(新)仅适用于 SDK 版本 3.5.0 或更高版本。
如需详细了解每个 SDK 版本中引入的变更,请参阅 Places SDK for Android 版本说明。
Places SDK for Android 的 Places API 版本
除了指定 SDK 版本号之外,您还必须选择 SDK 在 Google Cloud 控制台中调用的 Places API 服务:Places API 或 Places API(新)。您选择的 API 服务将与 SDK 版本号一起决定应用中提供特定功能的版本,例如自动补全或自动补全(新)。虽然您只能指定一个 SDK 版本号,但您可以同时启用 Places API 和 Places API(新)的 API 密钥,然后通过您在应用中初始化 SDK 的方法选择 SDK 调用的服务。不过,在大多数情况下,您需要启用 Places API(新)并使用(新)版本的 SDK 功能。
选择 SDK 版本和 API 服务
如需选择您的应用中可用的 SDK 功能,请执行以下操作:
- 在 Google Cloud 项目中,启用 Places API 和/或 Places API(新),或同时启用两者。如需了解详情,请参阅启用 API
- 在您的 API 密钥限制中,启用 Places API 和/或 Places API(新)。如需了解详情,请参阅限制 API 密钥。
在应用级 build.gradle 文件中,指定版本号。如需了解详情,请参阅安装。
通过调用
Places.initializeWithNewPlacesApiEnabled()
或Places.initialize()
方法来初始化您的应用。
如需详细了解如何选择 Places API 服务,请参阅设置您的 Google Cloud 项目。
每个版本中提供的 SDK 功能
下表显示了每项 SDK 功能所需的 SDK 和 API 版本:
特征 | 已针对 API 密钥启用 Places API | 初始化方法 | 最低 SDK 版本 |
---|---|---|---|
自动补全(新) | Places API(新) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
地点详情(新) | Places API(新) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
附近搜索(新功能) | Places API(新) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
地点照片(新) | Places API(新) | initializeWithNewPlacesApiEnabled() |
3.4.0 |
文本搜索(新) | Places API(新) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
地点自动填充 | Places API | initialize() |
|
当前地点 | Places API | initialize() |
|
地点详情 | Places API | initialize() |
|
地点照片 | Places API | initialize() |
选择要启用的版本时的注意事项
为帮助您决定选择哪个版本,请考虑以下事项:
- 如果您是刚开始使用 Places SDK for Android 的新客户,请先从 Places API(新)和新 SDK 入手。
- 如果您是现有客户,可以继续使用现有 SDK。不过,为了充分利用 Places SDK for Android(新)的性能提升和功能增强功能,您应该使用新版 SDK。迁移到新的 SDK 时无需进行迁移,只需按照选择 SDK 版本和 API 服务中的步骤操作即可。
- 在 Places SDK for Android(新)中,会话令牌从 3.5.0 版开始提供。如需了解详情,请参阅会话令牌。
- 使用地点自动补全 widget 发出的调用始终会调用地点自动补全,而不是地点自动补全(新);widget 调用不受初始化方法的影响。
- 地点照片(新)仅返回位图图片的 URI,而地点照片仅返回位图图片。
- 当前地点仅适用于 Places SDK for Android,不适用于 Places SDK for Android(新版)。
Places SDK for Android 中的增强功能(新)
本部分将介绍 Places SDK for Android 中添加的主要功能(新)。
在 Google Cloud 标准平台上实现
Places SDK for Android(新)在 Google Cloud 上的服务基础架构上实现。此实现带来了更安全、更值得信赖的平台。 这种标准设计让所有 SDK 都能实现一定程度的一致性,从而提高 Places SDK for Android(新)的开发效率。
性能改进
Places SDK for Android(新)改进了性能,因此值得替换使用现有 SDK 的应用。
新功能
Places SDK for Android(新)包含所有 SDK 功能的最新版本:
新的“文本搜索”服务
文本搜索(新功能)会根据一个字符串返回一组地点的相关信息,例如“北京烤鸭”“南京附近的鞋店”或“长安街 123 号”。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。
向地点详情(新)和地点照片(新)中添加了新的响应数据
地点详情(新)现在在响应
Place
对象中添加了新的 Review 类。Place 类包含支持此字段的新getReviews()
方法。调用getReviews()
可返回针对某个地点最多五条评价。地点照片(新)将
AuthorAttributions
添加到PhotoMetadata
类。AuthorAttributions
包含AuthorAttribution
对象的List
。
向地点照片添加了新 URI 响应(新)
您现在可以使用地点照片(新)返回图片位图的 URI。以前,您只能返回图片位图本身。
简化的价格方案
Places SDK for Android(新)的定价得到了简化,您只需为实际使用的数据量付费。简化的价格是通过字段列表(也称为字段掩码)实现的。
通过“地点详情”和“文本搜索”,您可以使用字段列表来控制要在响应中返回的字段列表。然后,您只需为请求的数据付费。使用字段列表是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。
如需详细了解这两种 SDK 的价格信息,请参阅用量和结算。
扩展的地点类型
新 SDK 添加了下表中显示的地点类型。这些类型会在“地点详情”和“文本搜索”响应中返回。您也可以在通过“文本搜索”进行搜索时使用这些新类型和现有类型。表 A 中包含新类型。
类型 | |||
---|---|---|---|
american_restaurant | discount_store | ice_cream_shop | sandwich_shop |
amusement_center | dog_park | indian_restaurant | school_district |
athletic_field | electric_vehicle_charging_station | indonesian_restaurant | seafood_restaurant |
auto_parts_store | event_venue | italian_restaurant | ski_resort |
banquet_hall | extended_stay_hotel | japanese_restaurant | spanish_restaurant |
barbecue_restaurant | 农场 | korean_restaurant | sporting_goods_store |
barber_shop | 农庄 | lebanese_restaurant | sports_club |
bed_and_breakfast | fast_food_restaurant | Marina | sports_complex |
brazilian_restaurant | ferry_terminal | 市场 | steak_house |
breakfast_restaurant | fitness_center | medical_lab | sushi_restaurant |
brunch_restaurant | french_restaurant | mediterranean_restaurant | swimming_pool |
bus_stop | gift_shop | mexican_restaurant | 定制 |
camping_cabin | golf_course | middle_eastern_restaurant | telecommunications_service_provider |
cell_phone_store | greek_restaurant | 汽车旅店 | thai_restaurant |
child_care_agency | grocery_store | national_park | transit_depot |
chinese_restaurant | guest_house | park_and_ride | truck_stop |
coffee_shop | hair_salon | performing_arts_theater | turkish_restaurant |
community_center | hamburger_restaurant | pizza_restaurant | vegan_restaurant |
顾问 | 直升飞机场 | playground | vegetarian_restaurant |
convention_center | hiking_area | 学龄前儿童 | vietnamese_restaurant |
村舍 | historical_landmark | private_guest_room | visitor_center |
courier_service | home_improvement_store | ramen_restaurant | wedding_venue |
cultural_center | 招待所 | resort_hotel | 批发商 |
dental_clinic | hotel | rest_stop |
除了这些新类型之外,Places API(新)还将以下类型从 Places API 的表 2 移至 Places API 的表 A(新)。这意味着,您现在可以在搜索中使用以下类型:
country
administrative_area_level_1
administrative_area_level_2
postal_code
locality