Places API(新版)快速参考

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(新版):

Places API(新):设置

官方 Places API(新版)软件包:

  • npm:@googlemaps/places
  • pypi:google-maps-places
  • go:cloud.google.com/go/maps

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 400 INVALID_ARGUMENT。解决方法:使用仅请求 id 字段(免费)的地点详情(新版)请求,刷新存储时间超过 12 个月的地点 ID。请参阅 /maps/documentation/places/web-service/place-id#refresh-id。

Places API(新版)的功能

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Places API(新版):生成式 AI

Places API(新):地点