迁移概览

欧洲经济区 (EEA) 开发者

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

迁移结算最佳实践

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

启用 Places API

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

大致变化

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

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

API 专属变更

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

下表显示了 Places Service 的功能如何映射到 Place 类的功能：

地点服务（旧版） 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 库的方式取决于所使用的引导加载程序。如果您的应用使用动态库导入，您可以在运行时使用 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：