Places API(新版)是一项 Web 服务,可返回有关场所、地理位置和地图注点的 JSON 位置数据。它支持文本搜索(新版)、附近搜索(新版)、自动补全(新版)、地点详情(新版)和地点照片(新版)。
Places API(新版):关键信息
- 产品:Places API(新版)
- 别名:Places API
- 类别:地点
- 平台:Web 服务 (REST)
- 运行位置:服务器(后端代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Places API(新版)概览
- 适用区域:全球。账单邮寄地址位于欧洲经济区 (EEA) 的项目需遵守《Google Maps Platform 欧洲经济区服务条款》(自 2025 年 7 月 8 日起生效),其中规定,除纬度、经度和地点 ID 之外,Places API 内容不得与任何地图搭配使用,除非通过 Places UI Kit。AI 赋能的地点、评价和区域摘要仅支持部分语言和地区。
Places API(新版):适用情形
在以下情况下使用 Places API(新版):
- 您需要通过服务器使用文本查询(文本搜索 [新])或围绕某个位置(附近搜索 [新])搜索地点。
- 您需要通过 Autocomplete(新版)从后端获取预输入地点或查询联想结果。
- 您有地点 ID,需要地址、电话号码、评分、评价或照片等详细信息。
- 您需要 AI 赋能的地点、评价或区域摘要。
在以下情况下,请勿使用 Places API(新版):
- 您正在构建原生 Android 应用。请改用 Places SDK for Android。
- 您正在构建原生 iOS 应用。请改用 Places SDK for iOS。
- 您正在构建浏览器 Web 应用,并希望在 JavaScript 中加载 Places 库。请改用 Maps JavaScript API。
Places API(新):设置
- 要启用的服务:
places.googleapis.com - 身份验证:API 密钥、OAuth 2.0
- 开始使用:设置 Places API(新版)
- 参考文档:Places API(新版)参考文档
- 价格:Places API(新版)用量和结算
- 政策:Places API(新版)政策
- 版本说明:Places API(新版)版本说明
官方 Places API(新版)软件包:
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API(新):相关产品
- 替代:Places API(旧版)
- 通常与以下 API 搭配使用:Geocoding API、Routes API、Address Validation API
Places API(新版):常见错误
- 问题:“地点详情(新)”“附近搜索(新)”和“文本搜索(新)”没有默认的返回字段列表;不含字段掩码的请求会返回错误。解决方法:使用
fields或$fields参数或X-Goog-FieldMask标头传递响应字段掩码。请参阅 /maps/documentation/places/web-service/choose-fields。 - 问题:如果省略 Autocomplete (New) 会话令牌,或者在会话结束后重复使用该令牌,则每个请求都会单独计费,计费 SKU 为“Autocomplete Requests”。修正方法:为每个会话生成一个新的会话令牌(建议使用 UUID v4),并以地点详情 (New) 或地址验证请求结束会话。请参阅 /maps/documentation/places/web-service/place-session-tokens。
- 问题:在未启用旧版 API 的项目中,调用 Places API(旧版)或 Maps JavaScript API
PlacesService的现有代码或 AI 生成的代码会失败,并显示LegacyApiNotActivatedMapError。解决方法:将调用迁移到 Places API(新版),并添加所需的字段掩码。请参阅 /maps/legacy#LegacyApiNotActivatedMapError。 - 问题:存储的地点 ID 可能会过时;地点详情(新版)随后会返回
NOT_FOUND(HTTP 404),格式错误或截断的 ID 会返回 HTTP 400INVALID_ARGUMENT。解决方法:使用仅请求id字段(免费)的地点详情(新版)请求,刷新存储时间超过 12 个月的地点 ID。请参阅 /maps/documentation/places/web-service/place-id#refresh-id。
Places API(新版)的功能
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
Places API(新版):生成式 AI
Places API(新):地点
- 根据查询字符串返回地点列表和地点详情。
- 返回特定位置附近的地点列表和地点详情。
- 根据查询字符串返回有关地点的自动补全结果。
- 返回特定地点的详细信息。
- 返回特定地点的照片。注意:请在每张照片旁边显示其作者信息(作者姓名,链接到其个人资料 URI)。每个平台的地点政策都要求这样做,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 调整地点照片的大小。
- 返回特定地点的评分和评价。注意:在 Places API(新版)网络服务中,“地点详情”是向 https://places.googleapis.com/v1/places/{placeId} 发出的 HTTP GET 请求,其中包含 X-Goog-FieldMask(例如 rating、userRatingCount、reviews);“文本搜索”“附近搜索”和“自动补全”使用 POST。在 Android 上,将 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 传递给 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中传递 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 指定地点信息响应中包含的数据字段。
- 指定要在地点信息响应中包含的地点类型。
- 返回用于在 Google 地图中打开某个地点的地点详情页面的 URI。
- 返回用于在 Google 地图中打开某个地点的路线页面的 URI。
- 返回 URI,以便在 Google 地图中打开某个地点的“撰写评价”页面。
- 返回用于在 Google 地图中打开某个地点的“阅读评价”页面的 URI。
- 返回用于在 Google 地图中打开某个地点的照片页面的 URI。
- 返回特定地点的 AI 生成的概览摘要。
- 返回 AI 赋能的区域摘要,其中描述了特定地点周围区域内的地点。
- 根据查询字符串返回位于预定义路线沿线的地点的相关信息。
- 返回从一组纬度/经度坐标到文本搜索地点的距离、行程时间和路线 URI。
- 根据一组纬度/经度坐标,返回到附近的地点 的距离、行程时间和路线 URI。
- 返回预定义路线的起点与根据查询字符串返回的每个地点(也位于该路线上)之间的距离、行程时间和路线 URI。
- 返回基于查询字符串返回的每个地点(这些地点也位于预定义路线上)与路线目的地之间的距离、行程时间和路线 URI。