claude-seo 补充 Google API 实战：Knowledge Graph、Custom Search 与 Web Risk 在 SEO 工作流中的落地

claude-seo 补充 Google API 实战Knowledge Graph、Custom Search 与 Web Risk 在 SEO 工作流中的落地【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 25 sub-skills 18 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, backlinks, local SEO, maps intelligence, semantic clustering, e-commerce SEO, international SEO, Google APIs, and PDF/Excel reporting. Optional DataForSEO, Firecrawl, and Banana extensions.项目地址: https://gitcode.com/gh_mirrors/cl/claude-seo本篇技术指南以 claude-seo 仓库中 supplementary-apis.md 为骨架系统讲解三个常被忽略但实战价值明确的 Google 补充 APIKnowledge Graph Search API品牌实体验证、Custom Search JSON API程序化搜索与 Web Risk APIURL 安全检测。读者将掌握每个 API 的端点、参数、响应结构与配额限制并了解它们在 claude-seo 的 seo-google 技能Tier 0 仅需 API Key中如何与 SKILL.md、google_auth.py 等仓库设施联动直接用于 Knowledge Panel 排查、去索引诊断与外部链接安全审计。一、补充 API 在 claude-seo 中的定位claude-seo 的 seo-google 技能围绕 Google 官方 SEO 数据设计主力能力包括 PageSpeed Insights v5、CrUX、Search Console、Indexing API 与 GA4。这些能力全部基于官方参考文档组织并通过/seo google command暴露。而三个补充 APIKnowledge Graph、Custom Search、Web Risk承担的是主流程之外的专项任务Knowledge Graph Search API验证品牌/实体是否出现在 Google Knowledge Graph 中判断 Knowledge Panel 是否存在Custom Search JSON API以受限方式程序化获取 Google 搜索结果Web Risk API检查 URL 是否被 Google Safe Browsing 标记为不安全。三者有一个共同特征认证方式均为 API Key属于 SKILL.md 定义的Tier 0仅配置api_key即可使用能力。这与需要 Service Account 或 GA4 配置的 GSC、Indexing、GA4 类命令形成了清晰的权限梯度——即使只拿到一个 Google Cloud API Key也能立刻跑通这三类检查。在 SKILL.md 的命令速查表中它们对应的入口是命令作用所需 Tier/seo google entity queryKnowledge Graph 实体检查验证品牌存在性0/seo google safety urlWeb Risk URL 安全检测恶意软件/社会工程标记0/seo google quotas展示全部 API 的速率限制表--值得注意的是SKILL.md 为这两条命令仅标注了参考文档即本篇主题的references/supplementary-apis.md未绑定独立脚本——也就是说它们由 Agent 直接调用对应 REST 端点完成属于轻量级的即查即用型命令。二、Knowledge Graph Search API验证品牌实体与 Knowledge Panel2.1 端点与参数Knowledge Graph Search API 用于在 Google 的 Knowledge Graph 中检索实体其端点为GET https://kgsearch.googleapis.com/v1/entities:search参数如下来自 supplementary-apis.md参数说明query搜索查询词ids指定实体 ID如/m/0d6lplanguages语言代码如entypes用于过滤的 Schema.org 类型如Organization、Personlimit最大返回结果数1–500keyAPI Key必填几个参数在实际使用中的要点ids允许你绕过关键词搜索直接按机器可读的实体 ID形如/m/0d6lp取实体数据适合在已知实体 ID 时做精确核对types与 Schema.org 类型对齐可与仓库中 seo-schema 的 schema 类型体系Organization、Person、LocalBusiness等配合检查实体在知识图谱中被归类为哪类limit上限 500日常品牌验证建议取较小值如 3–5以聚焦最相关实体。2.2 响应结构解读响应以itemListElement数组返回候选实体每个条目包含result与resultScore{ itemListElement: [{ result: { id: kg:/m/0d6lp, name: Google, type: [Organization, Corporation], description: Technology company, detailedDescription: { articleBody: Google LLC is an American..., url: https://en.wikipedia.org/wiki/Google }, image: { url: ... }, url: https://www.google.com }, resultScore: 4892.5 }] }实战中重点解读三个字段type实体的 Schema.org 类型可判断实体归类是否符合预期例如企业是否被识别为Organization而非PersondetailedDescription.articleBodyKnowledge Panel 中展示的长描述来源通常是维基百科摘要可用于判断品牌描述口径是否一致resultScore候选实体与查询的匹配度评分分数最高的条目通常即目标实体多实体重名时靠它做消歧。2.3 SEO 用途原文档明确列出三类场景验证品牌是否拥有 Knowledge Panel——查询品牌名若返回结果中存在匹配实体说明品牌已进入知识图谱检查实体消歧——当品牌与同名实体如同名人物、同名公司混淆时通过type与resultScore判断哪个实体排在前列发现相关实体——利用返回的关联结构寻找行业相关实体可用于内容与链接策略的实体层面研究。2.4 配额与认证配额100,000 次读取/天免费认证仅需 API Key无 OAuth/Service Account 要求。这与 rate-limits-quotas.md 中的统一配额表一致100,000 QPD、Free、API Key、按 GCP 项目计。2.5 仓库落地配置与安全细节在 claude-seo 中运行/seo google entity query依赖统一的 Google 凭据管理。配置位于~/.config/claude-seo/google-api.json核心字段在 google_auth.py 中被加载{ service_account_path: /path/to/service_account.json, api_key: GOOGLE_API_KEY, default_property: sc-domain:example.com, ga4_property_id: properties/123456789 }凭据检测命令为python3 scripts/google_auth.py --check --json。api_key存在即视为 Tier 0可运行entity与safety命令。两个与安全性直接相关的实现细节值得注意Header 认证形式google_auth.py 定义了标准请求头X-Goog-Api-Key: api_key这是 Google API 推荐的密钥传递方式优于把 key 拼进 URL query密钥脱敏google_auth.py 提供redact_google_api_key()在异常与输出文本中把key形式的查询参数替换为google_api_key_redacted、把AIza...前缀密钥替换为GOOGLE_API_KEY_REDACTED防止日志泄露且有对应测试 test_google_api_key_safety.py 覆盖。此外仓库强制要求所有接收用户 URL/查询的脚本先经 url_safety.py 的validate_url()校验见 CLAUDE.md 与 CONTRIBUTING.md拦截私网 IP、回环地址与云元数据端点作为 SSRF 防护基线——Agent 直接发起 Knowledge Graph 查询时同样应遵循该约定。三、Custom Search JSON API受限的程序化搜索与迁移警告3.1 端点与参数Custom Search JSON API 允许程序化调用 Google 搜索结果能力受限GET https://customsearch.googleapis.com/customsearch/v1参数说明keyAPI Key必填cxProgrammable Search Engine ID必填q搜索查询词num每页结果数1–10start起始索引最大 91dateRestrict日期限制如d30表示近 30 天gl国家/地区如uslr语言限制searchType设为image时执行图片搜索siteSearch限定到某个域名与 Knowledge Graph 不同本 API 除 API Key 外还必填cxProgrammable Search Engine ID需要先在 Programmable Search Engine 控制台创建自定义搜索引擎并获得 ID。3.2 关键限制务必前置告知原文档列出了三项硬性限制在使用前必须明确单次查询最多 100 条结果10 页 × 每页 10 条start上限 91⚠️ 2025 年起对新客户关闭现有客户须在2027 年 1 月前完成迁移计费每天前 100 次查询免费超过后按 $5/1,000 次计费上限 10,000 次/天。SKILL.md 的技术要点Technical Notes部分同样记录了这条关闭事实Custom Search JSON API is closed to new customers (2025)说明该限制已被纳入技能的运行时知识。由于 SKILL.md 未将 Custom Search 列为一条/seo google命令本 API 在原文档中的定位更多是了解其存在与局限——当用户需要真实 SERP 数据时文档给出的替代方案是For SERP data, prefer DataForSEO(/seo dataforseo serp) which has no such limitations.仓库中的 dataforseo 扩展 正是为补足这一缺口而存在它提供无上述限制的 SERP 数据能力含 seo-dataforseo SKILL 与 DATAFORSEO-SETUP.md。这与统一配额表 rate-limits-quotas.md 中的记录一致Custom Search 是该表内唯一100 次免费、$5/1K、10,000 QPD 上限的计费型 API。四、Web Risk APIURL 安全检测与去索引排查4.1 端点与参数Web Risk API 基于 Google Safe Browsing 数据判断 URL 是否被标记为不安全GET https://webrisk.googleapis.com/v1/uris:search参数说明threatTypes威胁类型MALWARE、SOCIAL_ENGINEERING、UNWANTED_SOFTWARE、SOCIAL_ENGINEERING_EXTENDED_COVERAGEuri待检测 URLkeyAPI Key必填威胁类型即 Safe Browsing 的威胁类别恶意软件、社会工程钓鱼、非预期软件以及社会工程的扩展覆盖类型。检查时可以传单个类型也可以一次性传入多种。4.2 响应解读安全 URL返回空的 threat 对象无命中。被标记 URL{ threat: { threatTypes: [MALWARE], expireTime: 2026-04-01T00:00:00Z } }threatTypes列出命中的威胁类型expireTime给出该标记的过期时间——过期后 Google 会重新评估因此历史被标记的 URL 在expireTime之后可能恢复安全。4.3 SEO 用途原文档给出三类核心场景排查去索引原因——如果页面流量骤降或被移除出索引先用 Web Risk 确认页面是否被标记为恶意/钓鱼这可能是 Google 拒绝收录或降权的直接原因验证竞品站点安全——评估竞品页面是否被标记辅助判断其排名波动是否与安全信誉有关审计外链——批量检查网站外链指向的域名/URL 是否危险防止外链污染信任度可结合仓库中的外链审计能力如 seo-backlinks 与 verify_backlinks.py 形成完整链路。4.4 配额与前提配额6,000 QPM每分钟查询数免费额度 100,000 次/月前提需要在 GCP 项目上启用计费billing enabled才能使用。需注意这与 Knowledge Graph 的纯免费、无需计费不同——Web Risk 虽然有免费额度但 GCP 项目必须挂接结算账户对应 rate-limits-quotas.md 成本汇总中Web Risk 在高用量下有付费档的说明。五、配额、成本与调用治理将三个补充 API 放入 seo-google 统一配额视图合并自 supplementary-apis.md 与 rate-limits-quotas.mdAPI每分钟每日/每月成本认证Knowledge Graph--100,000 QPD免费API KeyCustom Search--10,000 QPD上限前 100 次/天免费$5/1KAPI KeyWeb Risk6,000 QPM100K/月免费额度免费额度高用量付费API Key需启用计费三个 API 全部按 GCP 项目per project计配额与 GSC 的按站点per site、GA4 的按属性per property配额口径不同规划跨站点批量任务时需按项目维度合并计算。5.1 429 限流与指数退避rate-limits-quotas.md 为所有 API 提供统一的退避策略收到 429 或 5xx 时按 1s、2s、4s、8s、16s 递增等待最多重试 5 次并为每次等待加入 0–500ms 随机抖动避免惊群thundering herd若响应带Retry-After头则优先采用该头指定的秒数而非固定退避。5.2 常见错误码状态码含义处理建议400请求格式错误检查 URL/请求体格式401未授权刷新凭据403禁止访问检查 API Key 权限与 GCP 项目配置404未找到检查资源 ID / 项目配置429触发限流指数退避重试检查Retry-After头500 / 503服务端错误退避后重试5.3 成本边界据 rate-limits-quotas.md 的成本汇总seo-google 使用的全部 API 在常规用量下均免费Knowledge Graph 100K QPD 免费仅 Custom Search 与 Web Risk 存在高用量付费档——因此常规品牌验证与安全抽查基本零成本只有大规模程序化搜索场景才需要预算考量。六、在 claude-seo 工作流中落地6.1 命令入口与前置条件# 1. 检查凭据确认 Tier 0 可用 python3 scripts/google_auth.py --check --json # 2. 品牌实体验证Knowledge Graph # /seo google entity query # 3. URL 安全检测Web Risk # /seo google safety url配置缺失时按 auth-setup.md 的指引完成 Google Cloud 项目创建、API 启用与 Key 生成。SKILL.md 的错误处理约定要求未配置凭据时运行/seo google setup并列出仅需 API Key 即可使用的 Tier 0 命令这三个 API 均在列。6.2 与 Agent 工作流的整合agents/seo-google.md 定义了 seo-google 数据分析 Agent 的分层工作流Tier 0 阶段运行 PSI CrUX 并输出 Core Web Vitals 数据而 Knowledge Graph 与 Web Risk 同属 Tier 0 能力可在审计中作为补充证据源使用。从仓库结构可以推断的典型组合场景包括完整审计流程seo-audit技能会在检测到 Google 凭据时派生 seo-google Agent见 seo-audit SKILL.md此时entity检查可为 E-E-A-T 维度补充品牌是否被知识图谱认可的证据safety检查可补充站点信任与安全维度的证据GEO/AEO 与实体信号品牌实体在 Knowledge Graph 中的存在性是生成式引擎与 AI Overview 引用判断的常见信号与 seo-geo 关注的 AI 可见性主题SKILL.md 交叉集成部分提到 GSC 搜索外观含 AI Overview 引用存在自然衔接外链安全批量审计safety的单 URL 检测与 verify_backlinks.py 的外链验证流程可组合先做链接有效性验证、再做威胁标记筛查。6.3 结果输出约定按照 SKILL.md 的输出格式约定数据注明来源Google API field data、附带时效性说明结构化报告使用 assets/templates 下的模板并可调用python3 scripts/google_report.py生成 PDF/HTML 报告报告中 JSON 须通过review: {status: PASS}校验见 agents/seo-google.md。七、结语Knowledge Graph Search API、Custom Search JSON API 与 Web Risk API 是 claude-seo 中三个小而关键的补充数据源它们都以 API Key 认证、都属于 Tier 0 能力、都聚焦主流程之外的专项问题——品牌实体可见性、程序化搜索获取与 URL 安全信誉。其中 Custom Search 因 2025 年对新客户关闭实践上应以 DataForSEO 扩展承接 SERP 数据需求Knowledge Graph 与 Web Risk 则可长期免费用于审计工作流中的实体验证与安全排查。配合仓库统一的凭据管理google_auth.py、SSRF 防护url_safety.py与配额治理rate-limits-quotas.md这三类补充检查可以零成本地融入常规 SEO 审计为 E-E-A-T、信任度与去索引归因提供 Google 官方数据层面的支撑。【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 25 sub-skills 18 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, backlinks, local SEO, maps intelligence, semantic clustering, e-commerce SEO, international SEO, Google APIs, and PDF/Excel reporting. Optional DataForSEO, Firecrawl, and Banana extensions.项目地址: https://gitcode.com/gh_mirrors/cl/claude-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考