用 Python 调用 SEO 审计 API:批量审计网站并导出 CSV
一个可直接运行的 Python 脚本,调用 SEOReport SEO 审计 API:提交一批网站,轮询每份报告直到完成,再把所有问题导出到同一个 CSV 文件。
要用 Python 审计一批网站,每个网站只需调用 SEOReport REST API 三次:创建报告,轮询报告状态直到它不再处于排队或运行中,然后读取完成后的结果。下面的脚本针对一个纯文本的域名列表完成这些工作:同时运行几份报告,在两次轮询之间按 API 要求的时长等待,并为每个未通过或警告的问题生成一行 CSV。它需要 Python 3.8 或更高版本、requests 包,以及付费套餐提供的 API 密钥。
这里用到的每个端点和字段,要么列在开发者页面和 API 参考文档中,要么属于结果端点返回的 JSON。字段名已于 2026 年 10 月对照该返回数据核对过。
发出第一个请求之前需要准备什么
API 访问与账户绑定。拥有套餐后,您可以在账户设置中创建密钥,同一个密钥既可用于 REST,也可用于 MCP 服务器。每个请求都以 Bearer 令牌的形式发送它:
Authorization: Bearer YOUR_API_KEY
不要把密钥写在脚本里。将它导出为环境变量,在启动时读取:
export SEOREPORT_API_KEY="your key from account settings"pip install requests
关于额度,有两点会影响您如何准备列表。通过 API 审计的每个新网站都会消耗套餐中的一个额度,与在网站上操作完全相同。重新运行一个已有报告的网站不会再消耗额度。在大批量运行之前,请对比列表中新网站的数量与套餐的剩余额度;额度用完时,脚本会停止提交,并照常导出已完成的结果,但最好还是事先心中有数。
输入是一个每行一个网站的文本文件:
example.comexample.orgshop.example.net
每个网站都以首页地址提交。API 会读取您发送的 URL:裸域名或首页地址会得到一次网站审计,范围包括首页、站点地图列出的网页以及内部链接指向的网页;而带路径的 URL 只会单独审计那一个网页。对于一批网站来说,用裸域名就对了。
这几个调用如何配合
Diagram source
sequenceDiagram
participant S as Python 脚本
participant A as SEOReport API
S->>A: POST /api/v1/reports,附带网站 URL
A-->>S: report.jobId 和 report.status
loop 直到状态不再是 queued 或 running
S->>A: GET /api/v1/reports/jobId
A-->>S: report.status 和 pollAfterMs
end
S->>A: GET /api/v1/reports/jobId/result
A-->>S: 评分和完整问题列表
S->>S: 将未通过和警告的问题追加到 CSV提交调用会很快返回一个任务 ID。状态调用会告诉您报告进行到哪一步:queued、running,然后是 completed 或 failed。每个状态响应还带有 pollAfterMs,即 API 建议您在再次查询前等待的毫秒数。报告仍在运行时,这个值是几秒钟;报告完成后,它会降为 0。大多数报告在一分钟内完成。
第 1 步:提交每个网站并处理拒绝
提交函数发送 URL 并返回任务 ID。它还要决定 API 拒绝时该怎么办,因为批处理脚本必须分清“放慢速度”“停止”和“跳过这一个”。
"""Audit a list of sites with the SEOReport API and export the findings to CSV."""import csvimport osimport sysimport timeimport requestsBASE = "https://seoreport.dev/api/v1/reports"IN_FLIGHT = 5 # reports running at the same timeSUBMIT_PAUSE = 2 # seconds between submissionsMAX_WAIT = 600 # seconds before a report that never finishes is recordedCSV_FIELDS = ["site", "audited_url", "audited_at", "score", "status", "area","finding", "why_it_matters", "fix", "note", "job_id"]session = requests.Session()session.headers["Authorization"] = "Bearer " + os.environ["SEOREPORT_API_KEY"]class OutOfCredits(Exception):"""The account cannot run another new site, so stop submitting."""def submit(site, attempts=3):"""Create a report for one site. Returns (job_id, None) or (None, error)."""for _ in range(attempts):resp = session.post(BASE, json={"url": site}, timeout=60)if resp.status_code == 503:time.sleep(int(resp.headers.get("Retry-After", "30")))continuebody = resp.json()if resp.status_code == 402:raise OutOfCredits(body["error"])if not body.get("success"):return None, f"HTTP {resp.status_code}: {body.get('error')}"return body["report"]["jobId"], Nonereturn None, f"HTTP {resp.status_code} after {attempts} attempts"
它所处理的每种响应代码,对批处理而言含义各不相同:
Diagram source
flowchart TD
A["POST /api/v1/reports"] --> B{"HTTP 状态码"}
B -->|201| C["保存 report.jobId 并开始轮询"]
B -->|503| D["等待后重新发送,最多 3 次"]
B -->|402| E["额度已用完或没有套餐:停止提交"]
B -->|"429 或其他错误"| F["记录该网站的错误并继续"]402 表示账户目前无法再运行新网站,因此之后的每次提交都会以同样的方式失败。脚本会停止提交,让已在运行的报告跑完,并用 API 返回的信息把列表中剩余的网站标记为未审计,这样 CSV 中仍然保留所有已完成的内容。503 表示服务当时无法接收这份报告,因此脚本会等待后重新发送同一个网站:如果 API 发送了 Retry-After 标头就遵照执行,没有则等待 30 秒;连续 3 次被拒绝后,脚本会记录该网站并继续。429 不会重试。如果它来自单页审计上限,其 code 会说明是哪一个上限(PAGE_AUDIT_HOURLY_LIMIT 或 PAGE_AUDIT_DAILY_LIMIT),Retry-After 标头则给出距离上限解除还有多少秒,可能接近一小时,也可能接近一整天,所以脚本会记录信息后继续,而不是等待。其他错误,例如地址不是一个有效的公开网站,只与该网站本身有关:脚本会记录下来并继续。
第 2 步:礼貌地轮询,并同时保持几份报告在运行
一次提交 50 个网站,然后每秒轮询全部 50 个,是应当避免的做法。下面的函数最多同时运行 IN_FLIGHT 份报告,在两次提交之间暂停,并在每轮轮询之间按 API 建议的间隔休眠。
def get_status(job_id):resp = session.get(f"{BASE}/{job_id}", timeout=60)resp.raise_for_status()return resp.json()def audit(sites):"""Submit every site, keep IN_FLIGHT running, return one outcome per site."""pending, running, done = list(sites), {}, []while pending or running:while pending and len(running) < IN_FLIGHT:site = pending.pop(0)try:job_id, error = submit(site)except OutOfCredits as exc:done += [{"site": s, "job_id": "", "error": str(exc)} for s in [site] + pending]pending = []breakif error:done.append({"site": site, "job_id": "", "error": error})else:running[job_id] = (site, time.monotonic())time.sleep(SUBMIT_PAUSE)wait = 0for job_id, (site, started) in list(running.items()):envelope = get_status(job_id)state = envelope["report"]["status"]error = Noneif state in ("queued", "running"):if time.monotonic() - started < MAX_WAIT:wait = max(wait, envelope["pollAfterMs"] / 1000)continueerror = f"still {state} after {MAX_WAIT} seconds"elif state != "completed":detail = envelope.get("error") or {}error = f"{state}: {detail.get('code', '')} {detail.get('message', '')}".strip()del running[job_id]done.append({"site": site, "job_id": job_id, "error": error})if running:time.sleep(max(wait, 3))return done
除 queued 和 running 以外的所有状态都应视为最终状态,其中只有 completed 表示成功。MAX_WAIT 是一道安全限制,而不是预期耗时:大多数报告远在这个时限内完成,它只是防止某一份永远完不成的报告拖住整个批次。运行失败时,状态响应会带有一个 error 对象,其中包含 code、message 和 retryable 标志。DNS_FAILURE、CRAWLER_BLOCKED 和 TLS_ERROR 等代码描述的是网站本身的情况:域名无法解析、机器人规则拒绝了请求,或安全连接失败。重试这些情况只会得到同样的结果,而这个结果本身就值得告知网站所有者。我们的 CI 流水线教程也用同一个 error 对象来区分部署故障与无法运行的审计。
第 3 步:读取问题并写入 CSV
报告完成后,GET /api/v1/reports/{id}/result 会返回完整结果。在 report 中,有四个部分对导出很重要:
targetUrl是实际被审计的地址。如果您输入的地址重定向到同一域名下的另一个主机,例如从裸域名跳转到www,审计会跟随该重定向,所以请同时保留您的输入值和这个值。auditedAt表示审计运行的时间;脚本将其写入audited_at列。score.overall是该网站当天 0 到 100 分的评分。view.sections是报告各部分的列表。其中key为full_findings的那一部分包含detail.findings,每个问题对应一个对象。
每个问题都带有 status(fail、warn、pass 或 info)、指明问题涉及网站哪一部分的 areaLabel、title、解释其重要性的 whyItMatters,以及(针对未通过和警告的问题)fix。文字使用报告的语言。受影响的 URL 等针对具体网站的证据位于完整报告中,而不在这些字段里,所以本文最后一节会在 CSV 旁边保存一份完整报告。
def read_findings(job_id):resp = session.get(f"{BASE}/{job_id}/result", timeout=60)resp.raise_for_status()report = resp.json()["report"]section = next((s for s in report["view"]["sections"] if s["key"] == "full_findings"), None)if section is None or section["detail"] is None:state = section["state"] if section else "missing"raise RuntimeError(f"findings section is {state}")return report, section["detail"]["findings"]def export(outcomes, path):with open(path, "w", newline="", encoding="utf-8") as fh:writer = csv.DictWriter(fh, fieldnames=CSV_FIELDS)writer.writeheader()for item in outcomes:if item["error"]:writer.writerow({"site": item["site"], "status": "not_audited","note": item["error"], "job_id": item["job_id"]})continuetry:report, findings = read_findings(item["job_id"])except (RuntimeError, requests.HTTPError) as exc:writer.writerow({"site": item["site"], "status": "unreadable","note": str(exc), "job_id": item["job_id"]})continuefor finding in findings:if finding["status"] not in ("fail", "warn"):continuewriter.writerow({"site": item["site"],"audited_url": report["targetUrl"],"audited_at": report["auditedAt"],"score": report["score"]["overall"],"status": finding["status"],"area": finding["areaLabel"],"finding": finding["title"],"why_it_matters": finding["whyItMatters"],"fix": finding["fix"],"job_id": item["job_id"],})if __name__ == "__main__":with open(sys.argv[1], encoding="utf-8") as fh:sites = [line.strip() for line in fh if line.strip()]export(audit(sites), sys.argv[2])
运行时传入输入列表和输出路径:
python audit_sites.py sites.txt findings.csv
出了问题的网站会保留在文件中。无法审计的网站会得到一行 not_audited,原因写在 note 中;报告已完成但无法读取问题的网站会得到一行 unreadable。分享文件之前,请先按这两个值进行筛选:一个悄悄漏掉某个网站的 CSV,看起来就像那个网站没有任何问题。
预计会有多少行
几乎每个网站都会有若干行。2026 年 8 月 23 日至 10 月 4 日间,SEOReport 审计了 249 个外部网站,报告标记出的不同问题(未通过或警告项)中位数为 14 个;四分之一的网站有 17 个或更多,没有一个网站是零。
用这个中位数乘以列表长度,就能对文件大小做出合理的初步估计:一个由 40 个接近中位数的网站组成的列表,大约会产生 560 行。这么多行无法逐行阅读,所以才有 area 和 finding 两列。按 finding 排序,在多个网站上重复出现的问题就会排在一起:
import csvfrom collections import Counterwith open("findings.csv", encoding="utf-8") as fh:rows = [r for r in csv.DictReader(fh) if r["status"] == "fail"]for title, count in Counter(r["finding"] for r in rows).most_common(10):print(f"{count:>3} {title}")
当某个问题在 40 个网站中的 12 个上未通过时,请先寻找共同的原因:一个共用的主题、插件或主机模板,可能让 12 个问题变成 1 个修复、重复执行 12 次。这种比较之所以成立,是因为文件中的每个网站都用同一种方法检查过,而 audited_at 列记录了检查时间。如果通过 AI 聊天会话覆盖同样的范围,需要很多场彼此独立、每次都从头开始的对话;这篇针对 500 页网站的分析详细计算了所需的次数。
在 CSV 旁边保留完整报告
CSV 只是一个工作视图。若要存档,或要把完整诊断发给网站所有者,请按需要的格式下载每份报告:pdf、md、txt 或 json。
def save_report(job_id, path, fmt="pdf"):resp = session.get(f"{BASE}/{job_id}/download", params={"format": fmt}, timeout=120)resp.raise_for_status()with open(path, "wb") as fh:fh.write(resp.content)
PDF 包含封面、AI 执行摘要、分类明细和完整的问题列表。我们的带评分的报告包含哪些内容一文介绍了如何解读每个部分。
如果在第一次导出后还想持续关注同一批网站,可以用 PUT /api/v1/monitors 为它们注册每周监控,每个网站发送 {"url": ..., "alertEmail": ...}。监控包含在付费套餐中,不消耗报告额度,只有在出现新的严重或高严重性问题、某个严重问题被解决,或评分进入另一个区间时,才会向提醒邮箱发送邮件。
常见问题
再次运行脚本会再次消耗额度吗?
对于已有报告的网站不会。当某个网站已经有报告时,API 可能会返回那份现有报告,而不是运行新的审计,所以在把第二份 CSV 当作一次新的测量之前,请先检查 audited_at 列。每周监控总是会运行新的审计,因此更适合用来观察随时间发生的变化。
可以审计特定网页而不是整个网站吗?
可以。在输入文件中填写带路径的完整 URL,每个 URL 都会作为单个网页进行审计。单页审计有自己的每小时和每日上限。达到上限时,API 会返回 429,脚本会用 API 返回的信息把剩余的每个网页记录为未审计,方便您稍后再运行这些网页。如果想查看整个网站的情况,请只使用首页地址。
为什么被审计的 URL 与我列表中的不一样?
在审计之前,API 会跟随停留在同一域名内的重定向,所以 example.com 可能会以 www.example.com 的形式被审计。跳转到其他域名的重定向则不会被悄悄跟随:审计会保留您提供的地址,并把该重定向作为一个问题报告出来。用 site 列与您自己的记录关联,用 audited_url 列来阅读结果。
可以让 AI 智能体代替脚本来运行吗?
可以。同一个 API 密钥可以把任何支持 MCP 的智能体连接到 MCP 服务器,该服务器提供 create_report、get_report_status 和 get_report;我们的智能体设置指南介绍了具体配置。对于按计划运行的固定列表,脚本更合适,因为它每次运行方式完全一致,并会留下可供对比的文件。如果有人想针对某个网站的问题继续追问,智能体更合适。
CSV 能显示 Google 如何将每个网站编入索引吗?
不能。SEOReport 从外部审计的是每个网站在审计时提供的内容,不读取 Search Console 数据。要了解 Google 对某个网址做出了什么决定,请使用 Search Console;要了解网站上可能是什么导致了这一决定,请查看审计发现的问题。