如何查询Google My Business API获取Insights数据（供PHP/Python开发用）

前置权限校验（最高发的报错环节，必须先做） #

• 确认OAuth授权申请的scope完全覆盖Insights数据读取权限，不要仅授权商户基础资料的scope，否则调用Insights接口会直接返回无权限
• 把实际发起API调用的服务账号/授权用户邮箱，添加到目标GMB账户的正式站点管理者权限列表，仅获得API审批不等于拥有实际数据访问权限
• 通过账户列表接口拉取匹配的目标accountId与locationId，不要靠商户名称做模糊匹配，避免多账户场景下拉错其他商户的Insights数据

核心接口调用的规范要求 #

• 所有Insights类数据（曝光量、站点访问来源、用户交互行为、评论相关指标等）统一走专用的业务报表查询接口，不要拆分零散接口调用拉取同类数据
• 必传参数提前对齐校验：
  • 时间范围：单次请求最长支持拉取18个月的回溯数据，必须传入和目标站点设置完全一致的时区参数，否则日维度数据会出现错位偏差
  • 拆分维度：按需指定按日/按小时/按单站点的拆分规则，直接由接口返回拆分后的结构化数据，不要拉取聚合值后在本地二次拆分，降低重复请求量
  • 指标清单：把报告需要的所有Insights指标一次性传入，避免遗漏指标导致重复跑数
• 提前适配接口限流规则：默认单接口每秒最多10次请求额度，批量拉取全量站点数据时增加固定请求间隔，遇到429限流错误自动启用指数退避重试

技术栈适配提示 #

• Python栈：直接基于官方提供的Python客户端SDK开发，不需要从零拼接HTTP请求，SDK已经内置了OAuth token自动刷新、请求签名、基础异常重试逻辑，返回结果是结构化的对象，不需要手动处理JSON解析异常
• PHP栈：使用适配PHP 8+版本的GMB客户端封装库，同样内置完整的OAuth流程处理逻辑，注意把请求超时时间调整为30秒以上，避免拉取长周期多站点数据时因为响应时间过长触发断连

常见落地避坑提示 #

• 统一接口版本，不要混用旧版GMB接口和新版商家品牌接口的Insights能力，两个版本的返回字段、数据口径完全不兼容，混调会出现字段缺失
• 预留数据回补窗口：Insights类数据有最长3天的生成延迟，不要把报告的统计截止日期设为当日，避免拉到不完整的回补中数据
• 口径对齐：同一统计周期下，分日数据的累加值不一定等于周期汇总值，因为接口会对低流量的隐私敏感数据做脱敏隐藏，本地计算时要以接口直接返回的周期汇总值为准，不要手动累加分日数据凑数

内容的提问来源于stack exchange，提问作者Marco Baez