选择 SDK 版本

应用中可用的 Google 地图 SDK for Android 功能取决于您在应用配置中指定的 SDK 版本号（例如 3.5.0）、API 密钥上启用的 API 以及应用的初始化方式。本指南介绍了各个版本之间的差异，以及如何选择要在应用中启用哪些版本。

SDK 版本号

您在应用级 build.gradle 文件中指定的 SDK 的版本号决定了您的应用是否有权使用特定版本中添加的功能。例如，“自动补全（新）”仅在 SDK 3.5.0 或更高版本中提供。

如需详细了解每个 SDK 版本中引入的更改，请参阅 Android 版 Google 地图 SDK 版本说明。

Places SDK for Android 的 Places API 版本

除了指定 SDK 版本号之外，您还必须在 Google Cloud 控制台中选择 SDK 在其中调用的 Places API 服务：Places API 或 Places API（新版）。您选择的 API 服务与 SDK 版本号一起决定了应用中可用的特定功能（例如“自动补全”或“自动补全 [新]”）的版本。虽然您只能指定一个 SDK 版本号，但可以在 API 密钥中同时启用 Places API 和 Places API（新版），然后通过您在应用中用于初始化 SDK 的方法选择 SDK 调用的服务。不过，在大多数情况下，您都需要启用 Places API（新版），并在应用中使用 SDK 功能的（新版）。

选择您的 SDK 版本和 API 服务

如需选择应用中可用的 SDK 功能，请执行以下操作：

  1. 在您的 Google Cloud 项目中，启用 Places API 和/或 Places API（新版）。如需了解详情，请参阅启用 API
  2. 在 API 密钥限制中，启用 Places API 和/或 Places API（新版）。如需了解详情，请参阅限制 API 密钥。

  3. 在应用级 build.gradle 文件中，指定版本号。如需了解详情，请参阅安装。

  4. 通过调用 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 功能的最新版本：

新的文本搜索服务

文本搜索（新）可以根据一个字符串（例如，“北京烤鸭”“南京附近的鞋店”或“长安街 8 号”）返回一组地点的相关信息。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。

向“地点详情（新）”和“地点照片（新）”添加了新响应数据

向地点照片添加了新的 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
顾问 直升机停机坪 模拟环境 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 的 Table 2 移到了 Places API（新版）的 Table A。也就是说，您现在可以在搜索中使用以下类型：

  • country
  • administrative_area_level_1
  • administrative_area_level_2
  • postal_code
  • locality