seo-google

Google SEO APIs

共享数据缓存

步骤 0——检查共享数据缓存：

开始收集之前，请检查 .seo-cache/ 中是否有可供相关 SEO 技能复用的上下文。 参考 ../seo/references/shared-data-cache.md，了解架构和依赖关系图。

如果存在，请检查以下缓存文件：

• .seo-cache/site-meta.json：查看域名、业务类型、行业和抓取上下文

• .seo-cache/audit-scores.json：查看之前完整审计的优先事项

• .seo-cache/pages/{url-slug}/page-analysis.json：提供了 URL 时，查看页面级上下文

• 如果找到：解析并使用明显有效的字段（注明“正在使用 [date] 的缓存 [X]”）

• 如果缺失、损坏或不相关：继续收集新证据

• 如果用户说“refresh”或“re-run”：忽略缓存读取，并在写入时覆盖

直接访问 Google 自有的 SEO 数据。在基于抓取的分析（现有 codex-seo 技能）与 Google 实时现场数据之间搭建桥梁：真实的 Chrome 用户指标、实际索引状态、搜索表现和自然流量。

所有 API 均免费。设置需要 Google Cloud 项目，以及 API key 和／或 服务帐号——运行 /seo google setup 按步骤操作。

前置条件

执行任何命令之前，请检查凭据：

python scripts/google_auth.py --check --json

配置文件：~/.config/codex-seo/google-api.json

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

如果缺失，请阅读 references/auth-setup.md 并指导用户完成设置。

凭据级别

级别	检测条件	可用命令
0（API Key）	存在 api_key	pagespeed、crux、crux-history、youtube、nlp
1（OAuth/SA）	+ OAuth 令牌或服务帐号	级别 0 + gsc、inspect、sitemaps、index
2（完整）	+ 已配置 ga4_property_id	级别 1 + ga4、ga4-pages
3（Ads）	+ ads_developer_token + ads_customer_id	级别 2 + keywords、volume

运行命令之前，务必告知检测到的级别。

快速参考

命令	功能	级别
/seo google setup	检查／配置 API 凭据	--
/seo google pagespeed <url>	PSI Lighthouse + CrUX 现场数据	0
/seo google crux <url>	仅 CrUX 现场数据（p75 指标）	0
/seo google crux-history <url>	25 周 CWV 趋势分析	0
/seo google gsc <property>	Search Console：点击次数、展示次数、CTR、排名	1
/seo google inspect <url>	URL 检查：索引状态、规范网址、抓取信息	1
/seo google inspect-batch <file>	从文件批量检查 URL	1
/seo google sitemaps <property>	GSC 站点地图状态	1
/seo google index <url>	向 Indexing API 提交 URL	1
/seo google index-batch <file>	批量提交最多 200 个 URL	1
/seo google ga4 [property-id]	GA4 自然流量报告	2
/seo google ga4-pages [property-id]	自然流量排名靠前的落地页	2
/seo google youtube <query>	YouTube 视频搜索（观看次数、点赞数、时长）	0
/seo google youtube-video <id>	YouTube 视频详情 + 热门评论	0
/seo google nlp <url-or-text>	NLP 实体提取 + 情感分析 + 分类	0
/seo google entities <url-or-text>	仅实体分析（用于 E-E-A-T）	0
/seo google keywords <seed>	使用 Google Ads Keyword Planner 获取关键词建议	3
/seo google volume <keywords>	使用 Keyword Planner 查询搜索量	3
/seo google entity <query>	知识图谱实体检查	0
/seo google safety <url>	Web Risk URL 安全检查	0
/seo google quotas	显示所有 API 的速率限制	--

---

PageSpeed + CrUX

/seo google pagespeed <url>

Lighthouse 实验室数据 + CrUX 实际用户数据。

脚本： python scripts/pagespeed_check.py <url> --json 参考： references/pagespeed-crux-api.md 默认： 同时使用移动端和桌面端策略，涵盖所有 Lighthouse 类别。

输出将实验室评分（Lighthouse 某一时点的数据）与实际用户数据（Chrome 用户 28 天的指标）合并。CrUX 会优先尝试 URL 级数据，若无则回退到来源级数据。

/seo google crux <url>

仅提供 CrUX 实际用户数据（不运行 Lighthouse）。速度更快。

脚本： python scripts/pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

25 周 CrUX 历史趋势。显示 CWV 指标是在改善、稳定还是恶化。

脚本： python scripts/crux_history.py <url> --json 参考： references/pagespeed-crux-api.md

输出包括各项指标的趋势方向、变化百分比和每周 p75 值。

---

Search Console

/seo google gsc <property>

搜索分析：过去 28 天的点击次数、展示次数、CTR 和排名。

脚本： python scripts/gsc_query.py --property <property> --json 参考： references/search-console-api.md 默认： 28 天，维度为 query、page，类型为 web，限制为 1000。

包含快速见效机会检测：展示次数较高且排名在 4–10 位的查询。

/seo google inspect <url>

URL 检查：来自 Google 的实际索引状态。

脚本： python scripts/gsc_inspect.py <url> --json

返回：判定结果（PASS/FAIL）、覆盖状态、robots.txt 状态、索引状态、页面抓取状态、规范网址选择、移动设备适用性和富媒体搜索结果。

/seo google inspect-batch <file>

从文件批量检查（每行一个 URL）。每个网站每天限额为 2,000 次。

脚本： python scripts/gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

列出已提交站点地图的状态、错误和警告。

脚本： python scripts/gsc_query.py sitemaps --property <property> --json

---

Indexing API

/seo google index <url>

通知 Google 某个 URL 已更新。

脚本： python scripts/indexing_notify.py <url> --json 参考： references/indexing-api.md

Indexing API 官方适用范围仅包括 JobPosting 和 BroadcastEvent/VideoObject 页面。务必告知用户此限制。每日配额：200 次发布请求。

/seo google index-batch <file>

从文件批量提交 URL。会跟踪配额使用情况。

脚本： python scripts/indexing_notify.py --batch <file> --json

---

GA4 Traffic

/seo google ga4 [property-id]

自然流量报告：每日会话数、用户数、页面浏览量、跳出率和互动情况。

脚本： python scripts/ga4_report.py --property <id> --json 参考： references/ga4-data-api.md 默认： 28 天，按 Organic Search 渠道组筛选。

/seo google ga4-pages [property-id]

按会话数排名的自然流量热门落地页。

脚本： python scripts/ga4_report.py --property <id> --report top-pages --json

---

YouTube（视频 SEO）

YouTube 提及与 AI 可见度的相关性最高（0.737）。免费，仅需 API 密钥。

/seo google youtube <query>

在 YouTube 上搜索视频。返回标题、频道、观看次数、点赞数和时长。

脚本： python scripts/youtube_search.py search "<query>" --json 参考： references/youtube-api.md 配额： 每次搜索 100 个单位（免费每日 10,000 个单位）。

/seo google youtube-video <video_id>

详细的视频信息 + 标签 + 前 10 条评论。

脚本： python scripts/youtube_search.py video <video_id> --json 配额： 2 个单位（视频详情 + 评论）。

---

NLP 内容分析

Google 自有的实体/情感分析。可提升 E-E-A-T 评分。

/seo google nlp <url-or-text>

完整 NLP 分析：实体、情感和内容分类。

脚本： python scripts/nlp_analyze.py --url <url> --json 或 --text "..." 参考： references/nlp-api.md 免费额度： 每月 5,000 个单位。需要在 GCP 项目中启用结算。

/seo google entities <url-or-text>

仅提取实体（速度更快、配额消耗更少）。

脚本： python scripts/nlp_analyze.py --url <url> --features entities --json

---

关键词研究（Google Ads）

黄金标准的关键词搜索量数据。需要 Google Ads 账号。

/seo google keywords <seed>

根据种子词生成关键词建议。

脚本： python scripts/keyword_planner.py ideas "<seed>" --json 参考： references/keyword-planner-api.md 需要： 在配置中提供 Ads 开发者令牌和客户 ID（Tier 3）。

/seo google volume <keywords>

查询特定关键词的搜索量（以逗号分隔）。

脚本： python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json

---

补充功能

/seo google entity <query>

检查知识图谱实体，验证品牌是否存在。

参考： references/supplementary-apis.md 使用知识图谱搜索 API 和 API 密钥。

/seo google safety <url>

使用 Web Risk API 检查是否存在恶意软件／社会工程学标记。

参考： references/supplementary-apis.md

/seo google quotas

显示速率限制表。阅读 references/rate-limits-quotas.md。

---

报告

运行任何分析命令后，可选择生成 PDF／HTML 报告。

/seo google report <type>

生成包含图表和分析数据的专业 PDF 报告。

脚本： python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf

类型	输入	输出
cwv-audit	PSI + CrUX + CrUX 历史数据	Core Web Vitals 审计，包含仪表盘、时间线和分布图
gsc-performance	GSC 查询数据	Search Console 报告，包含查询表格和快速改进建议
indexation	批量检查数据	索引状态及覆盖率环形图
full	所有数据的汇总	全面的 Google SEO 报告（包含所有部分）

工作流：

1. 运行数据收集命令（pagespeed、gsc、inspect-batch 等）
2. 将 JSON 输出保存到文件：python scripts/pagespeed_check.py <url> --json > data.json
3. 生成报告：python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>

约定： 完成分析后，建议：“生成报告？使用 /seo google report <type>”

---

速率限制

API	每分钟	每天	身份验证
PSI v5	240 QPM	25,000 QPD	API 密钥
CrUX + History	150 QPM（共享）	无限制	API 密钥
GSC Search Analytics	1,200 QPM/site	30M QPD	服务账号
GSC URL Inspection	600 QPM	2,000 QPD/site	服务账号
Indexing API	380 RPM	200 次发布／天	服务账号
GA4 Data API	10 个并发请求	~25K tokens／天	服务账号

跨技能集成

• seo-audit：启动 seo-google Agent，获取实时 CWV 和索引数据（有条件）
• seo-technical：使用 pagespeed_check.py 获取真实 CWV 实测数据
• seo-performance：CrUX 实测数据补充 Lighthouse 实验室数据
• seo-sitemap：GSC 站点地图状态显示真实抓取／索引覆盖率
• seo-content：GSC 查询数据为关键词定位提供参考
• seo-geo：GSC 搜索外观数据包含 AI Overview 引用

输出格式

• CWV 指标：使用红绿灯评级（良好／需要改进／较差）
• 性能报告：使用包含可排序列的表格
• 始终注明数据时效性
• 将报告保存为 GOOGLE-API-REPORT-{domain}.md
• 使用 assets/templates/ 中的模板生成结构化输出

技术说明

• INP 于 2024 年 3 月 12 日取代 FID。切勿提及 FID。
• CrUX 的 CLS 值以字符串编码（例如 "0.05"）。脚本会处理解析。
• CrUX 返回 404 表示流量不足，并非身份验证错误。
• Search Analytics 数据会延迟 2–3 天。
• CrUX 中的 round_trip_time 于 2025 年 2 月取代 effectiveConnectionType。
• Custom Search JSON API 已不再向新客户开放（2025 年）。

错误处理

场景	操作
未配置凭据	运行 /seo google setup。列出仅需 API 密钥即可使用的 Tier 0 命令。
服务账号没有 GSC 访问权限	报告错误。说明：将 client_email 添加到 GSC > Settings > Users > Add。
CrUX 数据不可用（404）	报告 Chrome 流量不足。建议改用 PSI 实验室数据作为备用方案。
未找到 GA4 属性	报告错误。说明如何在 GA4 Admin > Property Details 中查找属性 ID。
超出 Indexing API 配额	报告每日 200 次的限制。建议优先处理最重要的 URL。
速率限制（429）	等待后使用指数退避策略重试。报告触发限制的 API。

写入共享数据缓存

完成所有工作后，如果工作流生成了可持久保存的发现，则将简洁的 JSON 摘要写入 .seo-cache/。 使用 ../seo/references/shared-data-cache.md 中的架构和命名规则；至少包含 cache_type、analyzed_at、来源 URL/域名、关键发现、问题、建议和工具限制。如果 .gitignore 中缺少 .seo-cache/，请将其添加进去。