Places API(旧版)快速参考

自 2026 年 10 月起,您将无法再为新的 Google Cloud 项目启用 Places API(旧版)。现有项目仍会得到全面支持。如需使用新功能并提升性能,请迁移到 Places API(新版)。

Places API(旧版):关键信息

  • 产品:Places API(旧版)
  • 也称为:Places API(旧版 Web 服务)、Places API Web 服务 (maps/api/place)
  • 类别:地点
  • 平台:Web 服务 (REST)
  • 运行位置:服务器(后端代码)
  • 发布阶段:GA
  • 生命周期:旧版
  • 替换为:Places API(新版)
  • 概览:Places API(旧版)概览

Places API(旧版):何时使用

在以下情况下使用 Places API(旧版):

  • 您维护着一个已启用 Places API(旧版)并调用 maps.googleapis.com/maps/api/place 端点的现有项目。
  • 您需要现有的“查找地点”“附近搜索”“文本搜索”“详情”“照片”或“自动补全”(旧版)调用,才能在迁移期间继续正常运行。

在以下情况下,请勿使用 Places API(旧版):

  • 您要启动一个新的 Google Cloud 项目。自 2026 年 10 月起,新项目将无法启用 Places API(旧版)。请改用 Places API(新版)。
  • 您需要使用“附近搜索”和“文本搜索”的新功能、OAuth 身份验证或字段掩码,以便仅为请求的字段付费。请改用 Places API(新版)。
  • 您需要在新代码中使用“查找地点(旧版)”或“查询自动补全(旧版)”。文本搜索(新版)和自动补全(新版)将取代它们。请改用 Places API(新版)。

Places API(旧版):设置

Places API(旧版):常见错误

  • 问题:如果地点详情(旧版)请求省略了 fields 参数或未指定任何字段,API 会返回所有字段并向您收取所有字段的费用。解决方法:请务必设置 fields 参数,或迁移到使用字段掩码的地点详情 (New)。请参阅 /maps/documentation/places/web-service/legacy/details。
  • 问题:附近搜索(旧版)和文本搜索(旧版)不支持指定要返回的字段。它们始终会返回一组固定的字段(地点详情字段的子集),并触发基本数据、联系人数据和氛围数据 SKU。解决方法:迁移到“附近搜索(新版)”或“文本搜索(新版)”并使用字段掩码,或者使用“查找地点(旧版)”并添加 fields 参数,以便仅请求您需要的字段并为其付费。请参阅 /maps/billing-and-pricing/sku-details/legacy#places_nearby-search-legacy-pro-sku。
  • 问题:photo_reference 无法缓存,并且可能会过期,因此存储的引用会停止工作。解决方法:在请求照片之前,先从“地点详情”“查找地点”“附近搜索”或“文本搜索”响应中获取新的 photo_reference。请参阅 /maps/documentation/places/web-service/legacy/photos。
  • 问题:从尚未启用 Places API(旧版)的项目调用该 API 会返回 REQUEST_DENIED,并显示出错提示“您正在调用旧版 API,但您的项目尚未启用该 API…”(LegacyApiNotActivatedMapError)。自 2026 年 10 月起,您将无法为新项目启用 Places API(旧版)。修复方法:为新项目使用 Places API(新版),并迁移现有应用。在迁移期间,您可以通过旧版页面上的反馈表单申请短期启用旧版 API。请参阅 /maps/legacy#LegacyApiNotActivatedMapError。

Places API(旧版):旧版和已弃用的功能

  • permanently_closed 响应字段:自 2020 年 5 月 26 日起已弃用。替代项:business_status 字段。请参阅迁移指南。
  • reference 响应字段:已弃用(自 2019 年 9 月 3 日起)。替代项:place_id 字段。请参阅迁移指南。
  • 附近搜索(旧版)name 请求参数:已弃用。替换:keyword 参数。请参阅迁移指南。