gsc-portfolio-audit

GSC 投资组合审计

回答 Search Console 账号中所有资源的“整体表现如何？”，这是单站点工具无法回答的问题，否则就得手动导出几十份报告。

设置

需要具有 https://www.googleapis.com/auth/webmasters.readonly 权限范围的 OAuth 刷新令牌：

export GOOGLE_GSC_CLIENT_ID=...      # or GOOGLE_CLIENT_ID
export GOOGLE_GSC_CLIENT_SECRET=...  # or GOOGLE_CLIENT_SECRET
export GOOGLE_REFRESH_TOKEN=...
export GSC_EXCLUDE="olddomain.com"   # optional, comma-separated
pip install requests

最常见的设置失败是在刷新令牌时出现 unauthorized_client。 这表示刷新令牌是由与你配对使用的 ID/密钥不同的 OAuth 客户端签发的。随着时间推移添加过 Google 集成的账号通常会有多个客户端；请匹配签发该令牌的那一组 ID 和密钥。

运行

python3 scripts/audit_gsc.py            # full: ranking + keyword diff for the top 12
python3 scripts/audit_gsc.py portfolio  # just the ranked table
python3 scripts/audit_gsc.py queries --site sc-domain:example.com
python3 scripts/audit_gsc.py --days 90  # quarter over quarter

标志：--days（时间窗口，与紧邻其前的时间窗口比较）、--site（可重复指定）、--top、--limit、--min-clicks。

各部分的含义

部分	解读方式
NEW	上一时段点击量为零的查询。查看增长实际来自何处。
RISING	增长 ≥50%。同时查看排名是否变化——如果没有变化，说明是需求增长，而不是排名提升。
DROPPING	在有实际流量的基础上下降 ≥40%。排名可以说明是哪种情况：排名下跌 = 排名损失；排名保持不变但点击量骤降 = 有内容抢走了你上方的点击量（AI Overview、新的 SERP 功能，或查询的形式发生了变化）。
LOST	之前有排名，现在没有数据。
CTR GAP	展示次数 ≥1,500，排名前 10，CTR 低于 2%。重写标题和描述，这是最容易实现的收益。

解读

• 先报告点击量，再报告展示次数。 一个大型资源可能大幅拉动整个投资组合的展示次数，从而掩盖其他所有资源都在增长的事实。
• 区分品牌词和非品牌词。 如果某个网站的全部关键词都是自己的名称（或竞争对手名称的拼写错误），那它就没有获客引擎，无论点击量看起来多好。请在报告中直言这一点。
• 整个网站在其核心词上的流量骤降，通常不是 SEO 问题。 诊断排名前先检查域名所有权：whois <domain> | grep -i "registrar\|updated date"，并检查域名是否仍能解析。域名过期、转让或存在争议，都会造成典型的排名断崖式下跌，再多 SEO 工作也无法解决。
• 投资组合表中的“new”表示上一时间窗口内点击量为零；对于近期上线的网站，这意味着刚刚上线，而非数据缺失。
• 不要跳过你看不懂的语言的查询。 在多市场网站中，增长通常来自非英语长尾词；请翻译有意思的查询，而不是将它们过滤掉。
• 返回 403 的资源可以验证其是否列出，但无法验证其搜索分析数据。脚本会报告此情况，而不是将其隐藏。

备注

• GSC 数据会延迟约 3 天；脚本会自动调整时间范围。
• 每个资源的两个时间段会并行获取，因此拥有 40 个资源的账号只需几秒钟。
• 每个时段最多获取 25,000 条查询数据，远高于任何单个网站在 28 天窗口内返回的数据量。