search console api 怎么用：四个服务、两个域名，和那个值得为它接一次的行数上限

search console api 是免费的，返回的就是你在 Search Console 界面上已经看到的同一批数字，而值得你去接它的差别只有一个：一次请求能拿回 25,000 行，不是屏幕上那一千行，而且同一条请求可以定时跑。它是四个服务，不是一个，其中两个还挂在不同的域名上，这是第一天最容易绊住人的地方。

读这篇前

你需要一个自己已经验证过的 Search Console 属性，并且能给这个属性加一个邮箱地址——要么是你自己的，要么是一个服务账号的。API 不会替你打开别人的数据，它读的是你账号能看到的那些属性。如果属性还没验证，先去看用五种形态读 performance report，那一步更便宜，因为 API 给你的只是同一份报表换了个不好看的形态。

这篇不需要你会写程序，但你需要能跑一条会打印 JSON 的命令。下面所有动作都在浏览器和终端里完成。

search console api 为什么是四个服务、两个域名

参考文档里列了四个服务，它们不是同一时间上线的，所以地址之间自己就对不上。Search Analytics、Sitemaps、Sites 三个都挂在一条还带着老名字的路径下面，webmasters/v3；URL Inspection 是后来加的，单独一个域名 searchconsole.googleapis.com，版本号也不一样。

上面这张表里有两个细节造出了第一天的大多数报错。属性标识写在地址里，它要么是你验证时那个一字不差的 URL 前缀、连结尾的斜杠一起，要么是 sc-domain:example.com 这种域名形态，两者不能互相替代。另外，取搜索数据这个方法是 POST，哪怕它只读：筛选条件和日期范围都放在请求体里，不是一段能粘进浏览器地址栏的 URL。

API 不是第二个 Search Console，它是同一批数字换了一个上限——而上限正是唯一值得为它学一次的理由。

按这个顺序做

四步，每一步都有一个能自己验证的完成标志。整个流程第一次大约二十分钟，之后就不花了。

1. 给一个项目打开这个 API。在 Google Cloud 控制台建一个项目，然后在上面启用 Search Console api。完成标志：该项目列表里这个 api 显示为已启用。
2. 建凭据。只跑一次的脚本，用「桌面应用」那种 OAuth 客户端最短，它能弹一次浏览器然后把 refresh token 存下来。要放在服务器上定时跑，就改建成服务账号，把它的 JSON 密钥下下来。完成标志：你手里有一份客户端密钥，或者一份密钥文件。
3. 把访问权给它。回到 Search Console，进属性设置，把服务账号的邮箱加成一个用户。完成标志：该邮箱出现在属性的用户列表里，权限是完整或受限。这一步跳过会得到一个 403，看起来像代码写错了。
4. 发一条请求，先看返回的形状。按页面分组，取一周数据，不加任何筛选。完成标志：拿到的行里带着 keys、clicks、impressions、ctr 和 position。

pip install google-auth google-auth-oauthlib requests

python3 -c "
import requests
from google.oauth2.credentials import Credentials

creds = Credentials.from_authorized_user_file('token.json',
          ['https://www.googleapis.com/auth/webmasters.readonly'])
site = 'sc-domain:example.com'
body = {'startDate': '2026-09-07', 'endDate': '2026-09-13',
        'dimensions': ['page'], 'rowLimit': 25000, 'dataState': 'final'}
url = 'https://www.googleapis.com/webmasters/v3/sites/' + site + '/searchAnalytics/query'
r = requests.post(url, headers={'Authorization': 'Bearer ' + creds.token}, json=body)
rows = r.json().get('rows', [])
print(len(rows), 'rows')
for row in rows[:5]:
    print(round(row['clicks'], 1), row['keys'][0])
"

交付物：一张路由表，和它要挤进去的两个天花板

这张路由表要跟上面那张放在一起。它省时间的地方在于，三条「读或推」的通路一直被当成一回事，而它们对谁能用、能用多少的规定各不相同。

中间那两行要单独看，因为搞错的人最多。Indexing API 不是通用的推送按钮，官方文档写明它不是给普通内容页用的，Indexing API 那一章讲了这种情况该改用什么。另外，URL Inspection 工具在界面上的「测试实际网址」在 API 这边没有对应方法，服务返回的是索引里已经存在的那一版的状态。

两个天花板比看上去好处理，因为它们是硬失败。所有配额超限返回的都是同一句话，光看报错分不出是哪一种，你得先知道自己更可能撞上哪一个。

调用次数底下还压着第二层限制，真正咬人的是它：一次请求是按它代表多少工作量计费的，不是按你发了几次。同一请求里既按页面分组又按搜索词分组，是文档点名的最贵写法；日期范围拉长同样更贵。一个脚本要两年的数据、还按页面加搜索词分组，它会先撞上预算，根本轮不到撞调用次数。

做错了会怎样，以及怎么发现

第一周会遇到的失败基本只有三种，而且每一种看起来都像另一个问题。知道该问哪个问题，光看报错就能定位。

1. 一个 401，其实是凭据类型不对。API key 标识的是项目，不是某个人，而这个 api 读的是私有数据。把 key 塞进请求头就会得到 401。要换成第二步那个 OAuth token，不是再申请一个 key。
2. 一个 403，其实是没给权限。服务账号是另一个身份，有它自己的邮箱地址，刚建出来时什么都看不到。在 Search Console 里把它加成属性用户，是跟「建服务账号」完全分开的一步，也正是被跳过的那一步。
3. 一个配额报错，其实是请求的形状不对。如果十分钟里只发了一条请求却报配额，你撞的不是每分钟上限，是长期预算，解法是把分组去掉，不是把脚本调慢。

有一条边界与其等着撞上，不如先写下来：本章覆盖的是参考文档列出的那四个服务。不在这四个服务里的报表没有公开的 API，生成式 AI 那几份报告属于另一件事，它的边界在AI 流量在 Search Console 里那一章，一句话概括是：那份报告回答的是「出现在哪些面」，不是「哪一条搜索词」。

另外，我们读到的这几份 API 文档里没有找到任何保留期声明，所以这一章不写数字。如果你要建的东西必须熬过这个窗口的变动，安全的做法和对任何外部数据源一样：定时拉，自己留一份。动手前先存一份基线就是把这件事落到单个页面上的写法。

常见问题

Search Console API 收费吗？

不收。它没有价格，上面那些配额就是全部成本，而且限制的是量，不是钱。你需要一个 Google Cloud 项目，但那是个管理容器，不是要付费的产品。

需要申请 API key 吗？

不需要，而且在这里 API key 用不了。API key 是给公开数据标识项目用的。Search Console 的数据属于某个人或某个组织，所以每次调用都要带 OAuth 2.0 token，token 上带两个 scope 之一：读写，或者只读。

能不能用服务账号，省掉每次登录？

能，而且只要是要定时跑的，就该这么做。服务账号有它自己的邮箱地址，你把这个地址加成 Search Console 属性的用户就行。它的凭据不会像用户 token 那样到期，这正是它存在的意义。

一次请求最多能拿多少行？

25,000 行；不填的话默认 1,000 行。再往后要发第二次请求，用偏移量从上次停下的地方接着取。多数站点一辈子用不到偏移量，页面和搜索词都很多的站会用到。

为什么各种配额超限报的都是同一句话？

因为 Google 对所有超限事件返回同一句「quota exceeded」。区分它们要靠失败出现的形状：十分钟里单独一条请求就失败，那是长期预算的问题；只有脚本全速跑时才失败，那是速率的问题。