关键词排名突然消失?用 Python、SQLite 和 SERP API 搭一套可解释的 SEO 监控

昨天关键词还排第 6,今天脚本却显示"没排名"。这到底是页面真的掉了,还是接口失败、地区变了,甚至只是返回结果不够多?

很多 SEO 监控脚本的问题不是"请求发不出去",而是能跑,却无法解释结果。如果把未命中写成 0,把不同国家和语言的数据混在一起,再用折线连起来,报表越漂亮,误导性反而越强。

本文不维护搜索页爬虫,而是用 Google SERP API、Python 和 SQLite 搭一个小型监测器。重点不是大屏,而是建立可复核的数据口径:什么算命中,什么算未命中,什么才算失败,以及两天的数据什么时候可以比较。
图片为 AI 生成的流程示意,不代表真实排名或效果数据。

先解决最容易混淆的三个结果

一次查询至少要区分三种状态:

  • found:接口正常返回,并在本次自然搜索结果集合里找到目标域名;
  • not_found:接口正常返回,但目标域名不在本次返回集合里;
  • error:网络、HTTP、JSON 解码或响应结构校验失败。

not_found 不能被记成第 11 名、100 名或 999 名。假设本次只请求 10 条自然结果,我们只能确认"本次返回集合中没有",并不知道集合之外的准确位置。

同样,error 也不能混进排名统计。否则一次超时就会被报表解释成"排名暴跌",把工程故障误当成 SEO 变化。

AceDataCloud 当前公开页面给出的 Google SERP 请求地址为:

复制代码
POST https://api.acedata.cloud/serp/google

公开示例中,自然搜索结果位于 organic,单条结果可读取 link 和 position。请求条件可包含查询词、国家、语言、页码和返回数量。字段最终应以当前接口文档为准。

配置文件也属于监测证据

创建 keywords.json:

复制代码
[
  {
    "query": "reusable travel tumbler",
    "target": "example.com",
    "country": "us",
    "language": "en"
  },
  {
    "query": "insulated coffee cup",
    "target": "example.com",
    "country": "us",
    "language": "en"
  }
]

target 是域名,不是整条页面 URL。国家和语言不要只放在程序默认值里,而要跟关键词一起保存。这样半年后回看数据库,仍能知道当时采用了什么搜索口径。

API Key 通过环境变量注入,不要写进代码、JSON、日志或截图:

复制代码
export ACEDATACLOUD_API_KEY='替换为自己的 Key'

一份可以追溯原始响应的完整脚本

下面的版本只依赖 Python 3 标准库。它固定查询第 1 页、10 条结果,把状态、条件、落地页和原始 JSON 一起写入 SQLite。

复制代码
import json
import os
import sqlite3
from datetime import datetime, timezone
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlparse
from urllib.request import Request, urlopen

ROOT = Path(__file__).resolve().parent
API_URL = "https://api.acedata.cloud/serp/google"


def normalize_host(value: str) -> str:
    value = value if "://" in value else "https://" + value
    hostname = urlparse(value).hostname or ""
    return hostname.lower().rstrip(".").encode("idna").decode("ascii")


def domain_matches(url: str, target: str) -> bool:
    hostname = normalize_host(url)
    return hostname == target or hostname.endswith("." + target)


def parse_rank(data: dict, target: str):
    if not isinstance(data, dict):
        raise ValueError("response is not an object")
    if data.get("error") or data.get("success") is False:
        raise ValueError("API reported failure")

    organic = data.get("organic")
    if not isinstance(organic, list):
        raise ValueError("organic is missing or invalid")

    hits = []
    for item in organic:
        if not isinstance(item, dict):
            raise ValueError("invalid organic item")
        position = item.get("position")
        link = item.get("link")
        if type(position) is not int or position < 1:
            raise ValueError("invalid position")
        if not isinstance(link, str):
            raise ValueError("invalid link")
        parsed = urlparse(link)
        if parsed.scheme not in ("http", "https") or not parsed.hostname:
            raise ValueError("invalid result URL")
        if domain_matches(link, target):
            hits.append((position, link))

    return min(hits) if hits else (None, None)


def fetch(payload: dict, token: str) -> dict:
    request = Request(
        API_URL,
        data=json.dumps(payload).encode("utf-8"),
        method="POST",
        headers={
            "Authorization": "Bearer " + token,
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        return json.loads(response.read().decode("utf-8"))


def main():
    token = os.environ["ACEDATACLOUD_API_KEY"]
    tasks = json.loads((ROOT / "keywords.json").read_text("utf-8"))
    db = sqlite3.connect(ROOT / "rankings.sqlite3")
    db.execute("""
        CREATE TABLE IF NOT EXISTS checks (
            checked_at TEXT NOT NULL,
            keyword TEXT NOT NULL,
            target TEXT NOT NULL,
            country TEXT NOT NULL,
            language TEXT NOT NULL,
            page INTEGER NOT NULL,
            requested_number INTEGER NOT NULL,
            returned_number INTEGER,
            status TEXT NOT NULL,
            position INTEGER,
            landing_url TEXT,
            error_type TEXT,
            raw_json TEXT
        )
    """)

    failures = 0
    for task in tasks:
        target = normalize_host(task["target"])
        if not target:
            raise ValueError("target must be a domain")
        payload = {
            "type": "search", "query": task["query"],
            "country": task["country"], "language": task["language"],
            "page": 1, "number": 10,
        }
        stamp = datetime.now(timezone.utc).isoformat()
        status = "error"
        position = landing_url = error_type = raw_json = None
        returned_number = None

        try:
            data = fetch(payload, token)
            raw_json = json.dumps(data, ensure_ascii=False)
            position, landing_url = parse_rank(data, target)
            returned_number = len(data["organic"])
            status = "found" if position is not None else "not_found"
        except HTTPError as exc:
            error_type = f"HTTPError:{exc.code}"
            failures += 1
        except (URLError, TimeoutError, json.JSONDecodeError, ValueError) as exc:
            error_type = type(exc).__name__
            failures += 1

        db.execute(
            "INSERT INTO checks VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
            (stamp, task["query"], target, task["country"], task["language"],
             1, 10, returned_number, status, position, landing_url,
             error_type, raw_json),
        )
        db.commit()
        print(task["query"], status, position if position else "-")

    db.close()
    raise SystemExit(1 if failures else 0)


if __name__ == "__main__":
    main()

域名匹配使用 URL 解析后的 hostname,不能直接做字符串包含判断。否则 notexample.com 也可能被当成 example.com。当前代码允许 shop.example.com 命中 example.com;如果业务要求只统计主站,把判断改成严格相等即可。

脚本还做了两件容易被忽略的事:记录 UTC 时间,展示报表时再统一转换时区;任一任务失败时返回非零退出码,让 cron、CI 或其他调度器能够发出告警。

报表先看"能不能比",再看涨了几位

先用 SQL 检查近 20 条记录:

复制代码
SELECT checked_at, keyword, country, language,
       status, position, returned_number
FROM checks
ORDER BY checked_at DESC
LIMIT 20;

只有在以下条件同时成立时,两次位置才适合直接比较:

  • 关键词、目标域名一致;
  • 国家、语言、页码和请求数量一致;
  • 两次都是 found;
  • 返回集合没有明显异常。

昨天第 8、今天第 5,可以描述为"在这两次同口径观测中上升 3 位"。但今天是 not_found,只能说"本次返回集合未检出";今天是 error,则应该先修监测链路。

不要仅凭一次排名变化就断言某次标题修改产生了效果。排名监测提供的是观察记录,不是因果证明。更稳妥的做法是把页面改动时间、连续观测和站点自身指标放在一起分析。

放进 cron 前,先做四项验收

把脚本保存为 /opt/seo/seo_monitor.py 后,可以设置每天执行一次:

复制代码
0 9 * * * /usr/bin/python3 /opt/seo/seo_monitor.py >> /opt/seo/run.log 2>&1

这只是示例。上线前至少检查:

  • cron 使用的时区是否符合报表口径;
  • 调度用户能否读取 Key、配置文件和数据库;
  • 日志是否限制权限并配置轮转;
  • 前一次任务未结束时,是否会与下一次重叠。

终端里能读到的环境变量,cron 不一定会继承。先用与 cron 相同的用户手动执行,再启用定时任务。

如果要扩展到多页,不要想当然地用"页码 × 每页数量"计算全局排名。应先核对接口中 position 的实际语义,保存每页原始结果,并设计跨页去重。小团队更适合先用少量关键词、固定首屏跑一周,确保三种状态都被正确解释。

请求预算可以这样估算:

复制代码
关键词数 × 国家/语言组合数 × 页数 × 每日执行次数

这个结果代表请求规模,不直接等于账单。单次费用、档位和失败请求如何计算,需要以当时的服务说明及实际用量记录为准,不要把脚本里的数字当成价格承诺。

最后:监控的目标不是"永远有一个名次"

可靠的 SEO 监控系统应该允许"未知"存在。未命中、请求失败和真实排名是三件不同的事;只有把搜索条件和原始响应留下来,趋势图才有解释价值。

先让数据可信,再做告警、周报和仪表盘。相比维护搜索页面选择器和代理,这套方案把工程精力集中在真正影响判断的地方:统一口径、数据质量与异常处理。

验证说明:本文代码按公开字段设计,未执行真实付费搜索请求,也未声称部署或获得排名提升效果。接口字段与能力以当前公开文档为准。

参考资料

相关推荐
prince_zxill1 小时前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
少司府1 小时前
嵌入式外设篇(三)GPIO·三:MCU系统结构、总线与统一编制
linux·python·stm32·单片机·嵌入式硬件·mcu·嵌入式软件
伞伞悦读2 小时前
【第90期】KNN分类回归流水线与K值对照的实验与排查
大数据·人工智能·python·深度学习·机器学习
console.log('npc')3 小时前
Python 学习教程 · 第4课:数据结构
数据结构·python·学习
honker_X3 小时前
Python字符串全攻略:从入门到精通
开发语言·python
贾公子3 小时前
异步检测的轮询与超时——别把「还没好」当成「失败了」
后端·python
吃我一窝jio3 小时前
Docker+Jenkins+K8s全流程部署
java·开发语言·笔记·python
欢乐马87914 小时前
优化|MPSolver 和 pywraplp 到底谁是谁?一次讲清 OR-Tools 的三层结构
python
mengge.cloud6 小时前
Python基础保姆级!从入门到入土
开发语言·python·云原生·pygame