Community研究与数据分析github.com

Google Search Console API 技能

使用 Google Search Console API (searchconsole v1 / webmasters v3) 进行搜索分析查询、网址检查、站点地图和网站管理,同时保持在配额限制内。

Google Search Console API 技能 是什么?

此技能提供对 Google Search Console API 的全面访问,涵盖性能报告(搜索分析)、网址检查、站点地图和网站列表。它专注于帮助开发者获取完整、正确的数据,同时避免配额超限。该技能详细解释了 Search Analytics 的查询模式、URL Inspection 的预算限制、配额管理策略,以及 OAuth 2.0 和服务账号的设置。支持平台包括 Python (google-api-python-client) 和 Node.js (googleapis) 等客户端库。此技能对于构建 GSC 数据管道、仪表盘、SEO 分析、批量网址检查以及调试常见的 403/配额超限错误至关重要。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Google Search Console API

Search Console API 提供对 Google Search Console 大部分功能的编程访问:性能报告(搜索分析)、网址检查、站点地图以及网站列表。它是一个 REST/JSON API。每次调用都需要 OAuth 2.0 和一个对相应资源拥有 Search Console 权限的用户(或服务账号)。

难点不在于发出请求,而在于在不超配额的情况下获取完整、正确的数据。本技能主要关注这一点。

何时使用此技能

  • 提取性能数据(点击次数、展示次数、点击率、排名)进行分析、仪表盘、数据仓库或 SEO 调查。
  • 大规模检查网址的索引状态、规范选择、robots/noindex 状态或富结果有效性。
  • 列出资源和权限,列出或提交站点地图。
  • 设计定时同步任务,或修复遇到 quotaExceeded、遗漏行或返回数字与 UI 不匹配的任务。

此 API 不涵盖的内容: 页面索引(覆盖率)报告、链接、核心网页指标、抓取统计信息、人工处置、移除操作以及“请求索引”按钮。对于现场核心网页指标,请使用 CrUX API;对于大型网站的大量原始性能数据,请使用 Search Console BigQuery 批量数据导出;单独的索引 API 仅支持 JobPosting / BroadcastEvent 页面。

四项服务

服务方法HTTP范围(最小)
搜索分析searchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
网址检查urlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
站点地图list / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
站点地图submit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
网站list / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
网站add / deletePUT / DELETE /webmasters/v3/sites/{siteUrl}webmasters

根 URL:https://searchconsole.googleapis.com/(当前发现文档,服务 searchconsole v1)。Google 文档中仍会出现较旧的 https://www.googleapis.com/webmasters/v3/... 路径,并且仍然适用于 webmasters/v3 资源。

范围: https://www.googleapis.com/auth/webmasters.readonly(只读)和 https://www.googleapis.com/auth/webmasters(读写)。除非任务确实需要提交/删除站点地图或添加/删除网站,否则请求只读范围。

资源标识符 (siteUrl) — 403/404 错误的首要原因

  • 域名资源: sc-domain:example.com
  • URL 前缀资源: https://www.example.com/ — 方案、主机和尾部斜杠必须与 Search Console 中的完全一致。
  • 在路径中,siteUrl 和 feedpath 必须完全 URL 编码(https%3A%2F%2Fwww.example.com%2F,sc-domain%3Aexample.com)。客户端库会自动执行此操作;原始 HTTP 则不会。
  • 始终先调用 sites.list,并完全按照返回的结果使用 siteUrl。siteUnverifiedUser 无法读取数据。

配额 — 在编写任何循环之前请先阅读

完整详细信息和工作表: references/LIMITS.md。

搜索分析

  • QPM 限制:每个网站 1,200 QPM、每个用户 1,200 QPM、每个项目 40,000 QPM 和 30,000,000 QPD。例如:一个用户访问 3 个网站,合计获得 1,200 QPM;两个用户访问一个网站,共享 1,200 QPM。
  • 负载配额(实际会咬人的那个):查询的内部成本,以 10 分钟(短期) 和 1 天(长期) 窗口进行跟踪。成本随以下因素增加:
    • 按 page 或 query 分组/过滤(两者同时使用是最昂贵的),
    • 日期范围的长度(6 个月 ≫ 1 天),
    • 重新查询已有数据。
  • 超出任何这些限制都会返回相同的 quotaExceeded 错误。短期:等待 15 分钟后重试。如果 单个 查询在 10 分钟窗口内仍然失败,则说明您超出了 长期(每日)负载配额 — 减少成本;重试无济于事,请等到第二天。

网址检查: 每个网站每天 2,000 QPD 和每分钟 600 QPM;每个项目每天 10,000,000 QPD 和每分钟 15,000 QPM。每个资源每天 2,000 次是真正的上限 — 计划抽样,不要计划“检查每个网址”。

其他所有内容(网站、站点地图):每个用户每秒 20 QPS 和每分钟 200 QPM;每个项目每天 100,000,000 QPD。

批处理不会节省配额:包含 n 次调用的批次计为 n 次请求。批处理仅节省 HTTP 开销。当前使用情况:Google Cloud 控制台 → API 和服务 → Search Console API → 配额。

搜索分析:获取完整、正确的数据

完整的请求/响应模式和配方: references/SEARCH-ANALYTICS.md。

推荐模式(来自 Google 的“所有数据”指南)

  1. 首先探查数据新鲜度。 仅按 date 分组查询最近约 10 天的数据 — 无过滤器,无其他维度。没有数据的日期将直接缺席。最终数据通常落后 2–3 天。
  2. 一次查询一天(startDate == endDate),每天一次,针对您需要的每个 type。每日一次的单天查询不应超过您的每日配额;而一个按 page+query 分组的 16 个月范围查询则会超过。
  3. 分页遍历结果:rowLimit 最大 25,000(默认 1,000),以 25,000 为单位递增 startRow,直到某页返回 少于请求的行数 或 0 行。
  4. 切勿重新拉取已最终确定的历史数据。 存储它;仅获取新日期的数据(如果您使用 dataState: "all",还可以重新获取最近未最终确定日期的数据)。
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
  "startDate": "2026-11-14",
  "endDate":   "2026-11-14",
  "dimensions": ["page", "query", "country", "device"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

必须向利益相关者解释的硬数据限制

  • API 返回顶部的行,而非所有行:无论分页如何,每天每种搜索类型最多返回 50,000 行(按点击次数排序)。
  • 按 page 和/或 query 分组/过滤会丢弃一些数据(以保持计算在约束范围内),并且匿名的稀有查询永远不会返回。因此,行之和 < 资源总计。要获得准确的合计值,请在没有 page/query 维度的情况下进行查询。
  • 总计因聚合方式而异:byProperty(每个资源去重)与 byPage(每个规范 URL)。如果您按 page 分组或过滤,则不允许使用 byProperty — 请使用 auto。
  • 日期为太平洋时间(America/Los_Angeles),而非 UTC。
  • Search Console 中的性能数据保留期约为 16 个月。如果您需要更长的历史记录,请持久化存储。

正确的指标计算

  • 分组的 CTR = sum(clicks) / sum(impressions)。切勿平均 CTR。
  • 分组的 排名 = 展示次数加权:sum(position × impressions) / sum(impressions)。切勿平均排名。
  • position 是基于 1 的平均最顶部位置;数值越低越好。

关键请求字段(快速参考)

  • dimensions:date、hour、query、page、country(ISO 3166-1 alpha-3,结果中为小写,例如 usa)、device(DESKTOP/MOBILE/TABLET)、searchAppearance、brandedClassification。
  • type:web(默认)、image、video、news(新闻标签页)、googleNews(news.google.com + 应用)、discover、webMultimodal(Lens / Circle to Search / 图片上传)。searchType 是已弃用的别名。
  • dimensionFilterGroups[].filters[]:{dimension, operator, expression};运算符 equals(默认,对 page/query 区分大小写)、notEquals、contains、notContains、includingRegex、excludingRegex(RE2)。组之间是 AND 关系;仅支持 groupType: "and"。
  • dimensionFilterGroups[].filterLists[]:针对 country / device 的多值精确匹配({"dimension":"country","expressions":["usa","can"]})。不能在同一维度上同时使用 filters 和 filterLists 进行过滤。
  • aggregationType:auto(默认)、byPage、byProperty(不适用于 discover/googleNews)、byNewsShowcasePanel。
  • dataState:final(默认)、all(包括新鲜的、尚未最终确定的数据)、hourly_all(hour 维度必需;可用约 10 天)。响应中的 metadata.firstIncompleteDate / firstIncompleteHour 标记了数字仍可能发生变化的位置。

注意事项

  • 搜索外观分两步操作:首先将 searchAppearance 作为唯一维度进行查询以列出类型,然后使用 searchAppearance equals <TYPE> 进行过滤并添加其他维度 — 每种类型一次查询。
  • brandedClassification(BRANDED / NON_BRANDED):仅支持 equals 运算符;不能与同一请求中的 query 过滤器结合使用;数据从 2026-02-21 开始,仅适用于具有足够流量的顶级资源。
  • 结果按点击次数降序排序,但按 date 分组时除外(日期升序)。平局是任意的 — 不要依赖排序进行去重。
  • 超出范围的 startRow 返回 200 且包含零行,而非错误。数据恰好位于 25,000 边界时,返回一个空的下页。
  • 当没有数据时,rows 不存在(而非 [])。

网址检查

完整模式、枚举和分类表: references/URL-INSPECTION.md。

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
  • 仅报告已索引的版本。它无法测试实时 URL,也无法请求索引。
  • inspectionUrl 必须在 siteUrl 之下。
  • 读取 indexStatusResult:verdict(PASS = 有效,NEUTRAL = 已排除,FAIL = 错误)、coverageState(人类可读字符串,例如“已提交并索引”)、robotsTxtState、indexingState、pageFetchState、lastCrawlTime、googleCanonical vs userCanonical、crawledAs。
  • 最有用的批量信号是 googleCanonical != userCanonical(Google 选择了不同的规范)。
  • mobileUsabilityResult 已弃用。ampResult / richResultsResult 在不适用时不存在。
  • 预算: 每个资源每天 2,000 次。优先考虑样本:按点击次数排序的热门页面、最近更改的模板、每个模板/模式一个 URL、来自新站点地图的 URL。

网站和站点地图

请参阅 references/SITES-AND-SITEMAPS.md。sites.list → siteEntry[] {siteUrl, permissionLevel},包含 siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser。sitemaps.list → sitemap[],包含 path、lastSubmitted、lastDownloaded、isPending、isSitemapsIndex、type、errors、warnings、contents[].submitted(contents[].indexed 已弃用 — 不要报告它)。submit / delete 不接受请求体,并且需要读写范围。这些是写操作。在调用它们之前,请与用户确认。

身份验证和设置

逐步指南,以及每种语言的库安装行: references/AUTH-AND-SETUP.md。

  1. 创建/选择一个 Google Cloud 项目 → 启用 Google Search Console API。
  2. 选择凭证:
    • 已安装/桌面 OAuth 客户端:供本地运行脚本的人类用户使用;用户在浏览器中同意,您存储刷新令牌。
    • 服务账号:供无人值守的任务使用。然后在 Search Console 中将服务账号电子邮件添加为资源的用户(设置 → 用户和权限)。受限用户对于读取操作已足够;写入操作需要所有者/完全用户。如果没有此步骤,每次调用都会返回 403。
    • 这些资源不接受 API 密钥;OAuth 2.0 是唯一支持的协议。
  3. 使用客户端库(推荐)— 例如 Python 的 google-api-python-client 配合 build("searchconsole", "v1", credentials=creds),Node 的 googleapis 配合 google.searchconsole("v1")。
from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)

resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
    "startDate": "2026-11-14", "endDate": "2026-11-14",
    "dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", [])   # 空时不存在

切勿打印、记录或提交令牌、客户端密钥或服务账号密钥。

错误和重试

完整映射: references/ERRORS.md。

症状原因操作
401 authError / expired令牌错误/已过期刷新令牌;检查范围
403 insufficientPermissions / “用户对此网站没有足够的权限”siteUrl 格式错误,或主体不是资源的用户sites.list,使用精确的 siteUrl;在 Search Console 中添加服务账号
403 accessNotConfigured项目上未启用 API启用 Search Console API
403/429 rateLimitExceeded、userRateLimitExceededQPS/QPM使用带抖动的指数退避
403/429 quotaExceeded(搜索分析)负载配额等待 15 分钟一次;如果单个查询仍然失败 → 长期负载:缩短日期范围或删除 page/query,明天恢复
400 invalidParameter / badRequest枚举错误、日期顺序错误、同一维度上的 filters/filterLists 混用、byProperty 与 page 混用修复请求;不要重试
500 / 503 backendError瞬时错误退避并重试(有界)

性能

references/BATCH-AND-PERFORMANCE.md:gzip(Accept-Encoding: gzip 以及包含 gzip 的 User-Agent)、通过 fields= 进行部分响应(例如 fields=rows(keys,clicks,impressions))、以及 HTTP 批处理(multipart/mixed,最多 1,000 次调用,按任意顺序执行,每次调用仍然计入配额)。

辅助脚本

scripts/gsc.py 是一个单文件 CLI,仅使用 Python 3.9+ 标准库。它将进度写入 stderr,将数据写入 stdout(默认为 JSONL,或 CSV/JSON)。它会分页、处理配额错误,并生成可在 Shell 中使用的 JSON 子集。

...

[为翻译而截断]

相关技能