如何使用 Google Search Console API？

Q: 如何使用 Google Search Console API？

创建 Cloud 项目、启用 API、通过 OAuth 授权，然后查询搜索表现数据、URL 检查和站点地图。以下是具体步骤和配额说明。

在 Google Cloud 控制台中创建项目，启用 Google Search Console API，创建 OAuth 2.0 凭据，然后使用对该资源拥有访问权限的 Google 账号登录。之后即可向四类资源发送请求：Search Analytics（点击、展示、CTR 和排名）、URL Inspection（索引状态）、Sitemaps（站点地图）以及 Sites（站点）。仅靠 API 密钥无法调用：每次请求都需要 OAuth 令牌，并且配额会限制你的请求量。

API 涵盖与不涵盖的内容

资源	方法	用途
Search Analytics	`query`	按查询词、页面、国家/地区、设备、搜索外观、日期或小时统计的搜索表现数据行
URL Inspection	`index.inspect`	单个 URL 的已索引版本：覆盖情况、上次抓取时间、规范网址
Sitemaps	`list`、`get`、`submit`、`delete`	管理资源已提交的站点地图
Sites	`list`、`get`、`add`、`delete`	已登录账号下的资源

API 的功能仅限于此。链接、抓取统计信息、页面索引报告和 Core Web Vitals 报告没有对应的接口，因此只能在 Search Console 界面中查看。URL Inspection 反映的是 Google 索引中的内容，而不是对页面的实时测试。

设置访问权限

在 Google Cloud 控制台中创建或选择一个项目。
为该项目启用 Google Search Console API。
配置 OAuth 同意屏幕，并创建 OAuth 客户端 ID。
申请授权范围：读取使用 https://www.googleapis.com/auth/webmasters.readonly，如需同时提交或删除站点地图，则使用 https://www.googleapis.com/auth/webmasters。
使用对该资源拥有权限的账号登录。读取搜索表现数据至少需要读取权限；API 看到的内容与该账号看到的完全一致。

第一个 Search Analytics 查询

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

站点标识放在路径中，并需进行 URL 编码：网域资源使用 sc-domain:example.com，网址前缀资源则使用带结尾斜杠的完整前缀，例如 https://www.example.com/。最重要的字段如下：

日期包含起止两端，并采用太平洋时间。
type 默认为 web；其他可选值为 image、video、news、googleNews 和 discover。每种类型需单独发起请求。
筛选条件放在 dimensionFilterGroups 中，运算符从 equals、contains 到 includingRegex、excludingRegex（RE2 语法）不等。
rowLimit 取值范围为 1 到 25,000（默认 1,000）；通过 startRow 翻页获取其余数据。
dataState 默认为 final;all 会包含最新但尚未最终确定的日期数据，hourly_all 则与 hour 维度配合使用。

每一行返回 keys、clicks、impressions、ctr（0 到 1）和 position，除非按日期分组，否则按点击量排序。

影响代码设计的限制

每个搜索类型每天 50,000 行。 使用 startRow 以 25,000 为步长翻页，遇到空响应即停止。若要获取尽可能多的数据，请每次查询一天。
负载配额。 同时按页面和查询词分组或筛选的请求开销最大，较长的日期范围比较短的成本更高。超出短期配额后，Google 会要求你等待 15 分钟。
请求速率。 每个站点和每个用户每分钟 1,200 次查询；每个项目每分钟 40,000 次、每天 30,000,000 次。
URL Inspection 配额。 每个资源每天 2,000 次检查，每分钟 600 次。
16 个月的历史数据， 数据通常在当天结束后的两到三天内可用。
数据行之和不等于总数。 查询级别的数据行会省略罕见查询词，而按页面分组时的展示次数统计方式与按资源分组不同，因此请从不含 query 维度的请求中读取总数。

常见错误

当资源是 https:// 时使用了 http://，或漏掉结尾斜杠，即使账号拥有访问权限也会返回权限错误。
在 URL Inspection 中请求资源之外的 URL 会被拒绝：该 URL 必须位于你传入的 siteUrl 之下。
一次调用中按查询词和页面分组整月数据，只会返回排名靠前的数据行。按天请求可以返回更多数据。

AutoPSEO 如何提供帮助

如果你不想自己维护 OAuth 和分页逻辑，AutoPSEO 通过 Google 登录进行连接，并通过自己的 REST API(路径为 /v1，附带 OpenAPI 3.1 文档)和 MCP 服务器提供相同的数据，使用 Account → API keys 中的 API 密钥授权。系统提供只读密钥，搜索分析接口每次调用最多返回 5,000 行，应用内的 URL Inspection 工具还会为你统计 Google 每天 2,000 次的配额使用情况。详见 MCP 和 API 密钥。如果想在不编写数据管道的情况下保留 16 个月之前的数据，请参阅 Search Console 会保留数据多久。

来源：Google 的 API 参考、Search Analytics query 方法、使用限制、获取全部数据以及授权指南。