迁移概览

欧洲经济区 (EEA) 开发者

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

迁移结算方面的最佳实践

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

启用 Places API

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

大致变化

下表列出了 PlacesServicePlace 之间的一些主要区别:

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: