迁移概览

欧洲经济区 (EEA) 开发者

本指南重点介绍了旧版 Places 服务与新版 Place 类之间的主要区别。升级到 Place 类可带来显著优势，包括性能提升和新的价格模式。为了充分利用 Places 并确保您的应用保持最新状态，请熟悉本指南中详述的变更。

迁移结算方面的最佳实践

如果您的 API 用量足够高，可以采用第二级定价，则此指南适用。迁移到较新版本的 API 时，您还需要为不同的 SKU 付费。为避免在过渡当月增加费用，我们建议您在尽可能接近月初时切换到生产环境中的新 API。这样可确保您在迁移月份达到最具成本效益的月度价格层级。如需了解价格层级，请参阅价格页面和价格常见问题解答。

启用 Places API

地点类依赖于 Places API 服务。如需使用新 Place 类的功能，您必须先在 Google Cloud 项目中启用 Places API（新）。如需了解详情，请参阅入门指南。

大致变化

下表列出了 PlacesService 和 Place 之间的一些主要区别：

PlacesService（旧版） Place（新）
方法需要使用回调来处理结果对象和 google.maps.places.PlacesServiceStatus 响应。 使用 Promise，并以异步方式运行。
方法需要进行 PlacesServiceStatus 检查。 无需进行状态检查，可以使用标准错误处理。
地点数据字段采用蛇形命名法。 地点数据字段采用驼峰式命名法。
仅限于一组固定的地点类型和地点数据字段。 提供更多定期更新的地点类型和地点数据字段。

特定于 API 的更改

Place 类提供了一个 API，用于使用地点库，还支持 promise 等新型使用模式。Place 类公开的地点数据字段和地点类型与旧版 Places 服务相同，并且包含许多新的地点数据字段值和地点类型值。

下表显示了 Places 服务的各项功能与 Place 类的各项功能之间的对应关系：

地点服务（旧版） 地点类（新）
地点数据字段 地点类数据字段
地点类型 地点类型
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
Autocomplete 类 PlaceAutocompleteElement 类
SearchBox 类 ---

加载 Places 库

应用加载 Places 库的方式取决于所使用的引导加载程序。如果您的应用使用动态库导入，您可以使用 await 运算符调用 importLibrary()，在运行时加载所需的库，如下所示：

const { Place } = await google.maps.importLibrary("places");

如果您的应用使用直接脚本加载标记，请在加载器脚本中请求 places 库：

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

详细了解如何加载 Maps JavaScript API。

本部分包含以下指南，可帮助您迁移应用以使用最新版本的 Places API：