Back to articles

用 Python 调用 SEO 审计 API:批量审计网站并导出 CSV

SEOReport Team·
apipythonautomationseo-auditcsv-export

一个可直接运行的 Python 脚本,调用 SEOReport SEO 审计 API:提交一批网站,轮询每份报告直到完成,再把所有问题导出到同一个 CSV 文件。

要用 Python 审计一批网站,每个网站只需调用 SEOReport REST API 三次:创建报告,轮询报告状态直到它不再处于排队或运行中,然后读取完成后的结果。下面的脚本针对一个纯文本的域名列表完成这些工作:同时运行几份报告,在两次轮询之间按 API 要求的时长等待,并为每个未通过或警告的问题生成一行 CSV。它需要 Python 3.8 或更高版本、requests 包,以及付费套餐提供的 API 密钥。

这里用到的每个端点和字段,要么列在开发者页面和 API 参考文档中,要么属于结果端点返回的 JSON。字段名已于 2026 年 10 月对照该返回数据核对过。

发出第一个请求之前需要准备什么

API 访问与账户绑定。拥有套餐后,您可以在账户设置中创建密钥,同一个密钥既可用于 REST,也可用于 MCP 服务器。每个请求都以 Bearer 令牌的形式发送它:

http
Authorization: Bearer YOUR_API_KEY

不要把密钥写在脚本里。将它导出为环境变量,在启动时读取:

bash
export SEOREPORT_API_KEY="your key from account settings"
pip install requests

关于额度,有两点会影响您如何准备列表。通过 API 审计的每个新网站都会消耗套餐中的一个额度,与在网站上操作完全相同。重新运行一个已有报告的网站不会再消耗额度。在大批量运行之前,请对比列表中新网站的数量与套餐的剩余额度;额度用完时,脚本会停止提交,并照常导出已完成的结果,但最好还是事先心中有数。

输入是一个每行一个网站的文本文件:

text
example.com
example.org
shop.example.net

每个网站都以首页地址提交。API 会读取您发送的 URL:裸域名或首页地址会得到一次网站审计,范围包括首页、站点地图列出的网页以及内部链接指向的网页;而带路径的 URL 只会单独审计那一个网页。对于一批网站来说,用裸域名就对了。

这几个调用如何配合

loop[直到状态不再是 queued 或 running]POST /api/v1/reports,附带网站 URLreport.jobId 和 report.statusGET /api/v1/reports/jobIdreport.status 和 pollAfterMsGET /api/v1/reports/jobId/result评分和完整问题列表将未通过和警告的问题追加到 CSVPython 脚本SEOReport APIPython 脚本SEOReport API
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 拒绝时该怎么办,因为批处理脚本必须分清“放慢速度”“停止”和“跳过这一个”。

python
"""Audit a list of sites with the SEOReport API and export the findings to CSV."""
import csv
import os
import sys
import time
import requests
BASE = "https://seoreport.dev/api/v1/reports"
IN_FLIGHT = 5 # reports running at the same time
SUBMIT_PAUSE = 2 # seconds between submissions
MAX_WAIT = 600 # seconds before a report that never finishes is recorded
CSV_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")))
continue
body = 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"], None
return None, f"HTTP {resp.status_code} after {attempts} attempts"

它所处理的每种响应代码,对批处理而言含义各不相同:

201503402429 或其他错误POST /api/v1/reportsHTTP 状态码保存 report.jobId并开始轮询等待后重新发送,最多 3 次额度已用完或没有套餐:停止提交记录该网站的错误并继续
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 建议的间隔休眠。

python
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 = []
break
if error:
done.append({"site": site, "job_id": "", "error": error})
else:
running[job_id] = (site, time.monotonic())
time.sleep(SUBMIT_PAUSE)
wait = 0
for job_id, (site, started) in list(running.items()):
envelope = get_status(job_id)
state = envelope["report"]["status"]
error = None
if state in ("queued", "running"):
if time.monotonic() - started < MAX_WAIT:
wait = max(wait, envelope["pollAfterMs"] / 1000)
continue
error = 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 旁边保存一份完整报告。

python
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"]})
continue
try:
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"]})
continue
for finding in findings:
if finding["status"] not in ("fail", "warn"):
continue
writer.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])

运行时传入输入列表和输出路径:

bash
python audit_sites.py sites.txt findings.csv

出了问题的网站会保留在文件中。无法审计的网站会得到一行 not_audited,原因写在 note 中;报告已完成但无法读取问题的网站会得到一行 unreadable。分享文件之前,请先按这两个值进行筛选:一个悄悄漏掉某个网站的 CSV,看起来就像那个网站没有任何问题。

预计会有多少行

几乎每个网站都会有若干行。2026 年 8 月 23 日至 10 月 4 日间,SEOReport 审计了 249 个外部网站,报告标记出的不同问题(未通过或警告项)中位数为 14 个;四分之一的网站有 17 个或更多,没有一个网站是零。

每个网站标记出的问题数,249 个外部网站,2026 年 8–10 月

用这个中位数乘以列表长度,就能对文件大小做出合理的初步估计:一个由 40 个接近中位数的网站组成的列表,大约会产生 560 行。这么多行无法逐行阅读,所以才有 area 和 finding 两列。按 finding 排序,在多个网站上重复出现的问题就会排在一起:

python
import csv
from collections import Counter
with 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。

python
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;要了解网站上可能是什么导致了这一决定,请查看审计发现的问题。

获取您网站的完整诊断

一份有据可依的报告和优先级行动计划,采用每月积分的订阅方案。