用同一个搜索词发两次 Search Console API 请求。一份看网站在这个词下的平均排名,另一份列出获得展示的网页和各自的平均排名。两次都用同一组日期、国家、设备和搜索类型。看这个词的整体排名变化,用第一份。想知道 Google 展示了哪些页面,用第二份。
发两次请求
先用有该网站资源权限的 Google 账号取得短期 OAuth 访问令牌。应用需要启用 Search Console API,授权时复制下面的只读范围。
https://www.googleapis.com/auth/webmasters.readonly
把拿到的令牌放进当前终端的 GSC_ACCESS_TOKEN 环境变量。还没配好授权,可按账户、授权范围和资源排查找缺哪一步。 Google OAuth 授权文档
把脚本存为 gsc_keyword.py。网域资源填 sc-domain:example.com。网址前缀资源照左上角显示的完整地址填写,包括协议、子域和末尾斜杠。日期包含首尾两天,按太平洋时间计算。例子只看美国手机的网页搜索,换成自己的日期和搜索词后执行 python gsc_keyword.py。
import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen
property_id = "sc-domain:example.com"
keyword = "custom enamel pins"
filters = [
{"dimension": "query", "operator": "equals",
"expression": keyword},
{"dimension": "country", "operator": "equals",
"expression": "USA"},
{"dimension": "device", "operator": "equals",
"expression": "MOBILE"},
]
common = {
"startDate": "2026-11-01",
"endDate": "2026-11-07",
"type": "web",
"dataState": "final",
"dimensionFilterGroups": [
{"groupType": "and", "filters": filters}
],
}
encoded = quote(property_id, safe="")
endpoint = (
"https://www.googleapis.com/webmasters/v3/sites/"
f"{encoded}/searchAnalytics/query"
)
token = os.environ["GSC_ACCESS_TOKEN"]
def fetch(dimensions, aggregation, expected):
payload = dict(
common, dimensions=dimensions,
aggregationType=aggregation, rowLimit=25000,
)
request = Request(
endpoint, data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
method="POST",
)
with urlopen(request, timeout=30) as response:
data = json.load(response)
rows = data.get("rows", [])
if rows and data.get("responseAggregationType") != expected:
raise ValueError("Unexpected response aggregation")
return rows
def print_rows(label, rows):
print(label)
if not rows:
print("No rows for these filters")
for row in rows:
print(row["keys"][0],
f"impressions={row['impressions']:g}",
f"position={row['position']:.2f}",
f"clicks={row['clicks']:g}",
sep="\t")
print_rows("PROPERTY", fetch(["query"], "byProperty", "byProperty"))
print_rows("PAGE", fetch(["page"], "auto", "byPage"))
两次请求共用 common。第一组按资源汇总,第二组按 page 分组时把 aggregationType 设为 auto,并核对 Google 返回的类型。页面行按规范网址汇总。详情见 Search Analytics API。
脚本会显示哪两份结果
下面是模拟输出。PROPERTY 从搜索词开始,PAGE 从网页地址开始。
PROPERTY
custom enamel pins impressions=14 position=4.71 clicks=0
PAGE
https://www.example.com/a/ impressions=12 position=4.00 clicks=0
https://www.example.com/b/ impressions=6 position=9.00 clicks=0
也可以打开 GSC「效果 → 搜索结果」对照。沿用脚本的查询、网页搜索、美国、移动设备和相同的完整日期,再开启「平均排名」。上方图表看资源,切到「网页」标签看各网址。这两份历史数据都不能回答「现在在某个城市手动搜排第几」。需要查眼前结果时,可看谷歌关键词排名查询方法。
为什么全站 14 次,网页加起来有 18 次
把输出里的两个地址当成一个定制服务页 A 和一篇报价指南 B。假设有 8 次只出现 A,位置为 4。有 2 次只出现 B,位置为 9。还有 4 次 A 和 B 同时出现,位置仍分别是 4 和 9。
页面表分别算,A 出现 12 次,B 出现 6 次。两页同时出现的那 4 次,在全站报表里每次只算一次展示,位置取更靠前的 A。于是全站有 12 次位置为 4、2 次位置为 9,平均值是 (12 × 4 + 2 × 9) ÷ 14 ≈ 4.71。若把两个页面的排名直接平均,会得到 6.5,和这 14 次展示的平均位置不同。 Google 的展示和排名说明
没有数据,或者出现了另一张页
脚本显示 No rows for these filters 时,先在同一资源复核筛选。API 的 equals 对查询词区分大小写。核过拼写后,可以只放宽日期再试。示例脚本只取第一页。若按页面查满 25,000 行并确实需要更多,在第二次请求的请求体加入 "startRow": 25000;后续每次加 25,000,直到返回少于一页或为空。日期、过滤器和聚合方式保持不变。即使翻页,API 也不保证提供所有行。无数据时将排名留空,401 或 403 则先核令牌与权限。 Search Console 效果报告说明
如果常出现的是报价指南,服务页很少有展示,打开两页看各自回答了什么。报价指南可以继续讲价格,服务页则要让人找到规格、起订量和询价方式。只有两个页面服务同一任务时,才值得按关键词与页面分配重做分工。
常见问题
为什么脚本里是 4.71,我刚才搜是第 9?
4.71 是例子里一段时间、一个市场和设备下的平均位置。手动搜索是那一刻的一次结果,分开记录。
为什么 PAGE 里没有带参数的原始 URL?
页面数据按规范网址汇总。先在「网址检查」看 Google 选中的规范地址,再到 PAGE 里找那个地址。
数据空了,能记成排名 0 吗?
记「该条件下未返回数据」,把排名字段留空。HTTP 请求失败时则记录错误,方便恢复后重跑。







