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.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| 网址检查 | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| 站点地图 | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| 站点地图 | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| 网站 | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| 网站 | add / delete | PUT / 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 的“所有数据”指南)
- 首先探查数据新鲜度。 仅按
date分组查询最近约 10 天的数据 — 无过滤器,无其他维度。没有数据的日期将直接缺席。最终数据通常落后 2–3 天。 - 一次查询一天(
startDate == endDate),每天一次,针对您需要的每个type。每日一次的单天查询不应超过您的每日配额;而一个按 page+query 分组的 16 个月范围查询则会超过。 - 分页遍历结果:
rowLimit最大 25,000(默认 1,000),以 25,000 为单位递增startRow,直到某页返回 少于请求的行数 或 0 行。 - 切勿重新拉取已最终确定的历史数据。 存储它;仅获取新日期的数据(如果您使用
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、googleCanonicalvsuserCanonical、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。
- 创建/选择一个 Google Cloud 项目 → 启用 Google Search Console API。
- 选择凭证:
- 已安装/桌面 OAuth 客户端:供本地运行脚本的人类用户使用;用户在浏览器中同意,您存储刷新令牌。
- 服务账号:供无人值守的任务使用。然后在 Search Console 中将服务账号电子邮件添加为资源的用户(设置 → 用户和权限)。受限用户对于读取操作已足够;写入操作需要所有者/完全用户。如果没有此步骤,每次调用都会返回 403。
- 这些资源不接受 API 密钥;OAuth 2.0 是唯一支持的协议。
- 使用客户端库(推荐)— 例如 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、userRateLimitExceeded | QPS/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 子集。
...
[为翻译而截断]