自 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-backend.googleapis.com - 身份验证: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参数。请参阅迁移指南。