知识库文章

GSC API 怎么查一个关键词的排名和对应页面?

文章摘要
先在 Search Console 认清全站排名和网页排名,再用两次只读 API 请求自动取数。附 Python 脚本和例子。

本页阅读目录

同一场搜索显示两个网址,按资源计一次,按两个页面各计一次

用同一个搜索词发两次 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 请求失败时则记录错误,方便恢复后重跑。

我专注 Google SEO、独立站增长与 AI 工作流,实践覆盖 WordPress 外贸 B2B 询盘站和 Shopify DTC 品牌站。从关键词研究、网站架构到内容与技术优化,我关注每一步怎样影响流量、询盘和购买。

本站分享我的项目方法与复盘,说明为什么这样做、具体怎样执行,以及如何判断改动是否有效。

雨果跨境观察员 · 公众号、抖音、小红书同名账号:跨境YOUNG。

学习与查找

从入门开始,或回到问题目录:

关于跨境YOUNG

跨境YOUNG整理WordPress建站、Google SEO与AI SEO / GEO方法,并提供建站、代运营和顾问服务。

需要有人持续推进SEO?

网站已上线,但页面、内容、技术、内链和月度数据没有持续推进?可先诊断范围与优先级,再按月执行与复盘。

最具性价比的服务器

Hostinger 适合预算有限的新站和中小企业 WordPress 网站,托管、备份与基础性能配置比较完整。通过专属链接可享 20% 折扣,购买前再核对机房位置和续费价格。

专属链接含 20% 折扣;跨境YOUNG可能获得佣金,不会增加你的购买成本。