PythonでSEO監査API:サイト一覧を監査してCSVに出力
SEOReportのSEO監査APIを使う実用的なPythonスクリプトです。サイトの一覧を送信し、各レポートの完了までポーリングして、検出事項を1つのCSVに書き出します。
Python でサイトの一覧を監査するには、サイトごとに SEOReport REST API を3回呼び出します。レポートを作成し、待機中・実行中でなくなるまでステータスをポーリングし、完了した結果を読み取ります。以下のスクリプトは、ドメインを並べたプレーンテキストの一覧に対してこれを実行し、複数のレポートを同時に走らせ、ポーリングの間隔は API が指定するだけ待ち、不合格または警告の検出事項1件につき CSV の1行を出力します。必要なのは 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
一覧の作り方を左右する、クレジットに関する事実が2つあります。API で新しいサイトを監査するたびに、ウェブサイトから実行する場合とまったく同じように、プランのクレジットを1つ消費します。すでにレポートがあるサイトを再度実行しても、追加のクレジットは消費しません。大量のバッチを実行する前に、一覧に含まれる新しいサイトの数とプランの残りクレジットを比べてください。クレジットがなくなるとスクリプトは送信を止め、完了した分はエクスポートしますが、事前に把握しておくに越したことはありません。
入力は、1行に1サイトを書いたテキストファイルです。
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分以内に完了します。
ステップ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 は再試行しません。ページ監査の上限による 429 では、code がどちらの上限か(PAGE_AUDIT_HOURLY_LIMIT または PAGE_AUDIT_DAILY_LIMIT)を示し、Retry-After ヘッダーが上限の解除までの秒数を示します。これは1時間近く、あるいは1日近くになることがあるため、スクリプトは待たずにメッセージを記録して先に進みます。それ以外、たとえば有効な公開ウェブサイトではないアドレスなどは、そのサイト固有の問題なので、記録して先に進みます。
ステップ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 は想定される所要時間ではなく安全のための上限です。ほとんどのレポートは十分にその範囲内で完了し、この上限は、いつまでも終わらないレポートが1件あるせいでバッチ全体が終わらなくなるのを防ぐためだけのものです。実行が失敗した場合、ステータスのレスポンスには code、message、retryable フラグを持つ error オブジェクトが含まれます。DNS_FAILURE、CRAWLER_BLOCKED、TLS_ERROR などのコードはサイト自体の状態を表しています。それぞれ、ドメインの名前解決ができなかった、ボット対策のルールがリクエストを拒否した、安全な接続に失敗した、という意味です。これらは再試行しても同じ結果になり、その結果自体がサイトの所有者に伝える価値のある情報です。CI パイプラインのレシピでも、同じ error オブジェクトを使って、デプロイの不具合と実行できなかった監査を区別しています。
ステップ3:検出事項を読み取り、CSV に書き出す
レポートが完了すると、GET /api/v1/reports/{id}/result が結果全体を返します。report の中で、エクスポートに関係するのは次の4つです。
targetUrlは、実際に監査されたアドレスです。入力したアドレスが同じドメイン内の別のホストにリダイレクトする場合、たとえばドメインだけのアドレスからwwwへリダイレクトする場合、監査はそれに従います。そのため、入力したアドレスとこの値の両方を残しておきます。auditedAtは、監査がいつ実行されたかを示します。スクリプトはこれをaudited_at列に書き込みます。score.overallは、そのサイトのその日のスコアで、0から100の値です。view.sectionsはレポートのセクションの一覧です。keyがfull_findingsのセクションにdetail.findingsがあり、検出事項1件につき1つのオブジェクトが入っています。
各検出事項には、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 の行が1行出力され、note に理由が入ります。レポートは完了したものの検出事項を読み取れなかった場合は、unreadable の行が1行出力されます。ファイルを共有する前に、この2つの値で絞り込んでください。サイトが黙って抜け落ちた CSV では、問題のないサイトと見分けがつかなくなります。
出力される行数の目安
ほぼすべてのサイトについて行が出力されると考えてください。2026年8月23日から10月4日にかけてSEOReportが監査した外部ウェブサイト249サイトでは、レポートで検出された個別の問題(不合格または警告の検出事項)の中央値は14件で、4分の1のサイトでは17件以上、0件のサイトは1つもありませんでした。
この中央値に一覧のサイト数を掛ければ、ファイルの大きさの目安になります。中央値に近いサイトが40サイトなら、およそ560行です。1行ずつ読むには多すぎるので、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 は新しい監査を実行せずに既存のレポートを返すことがあります。そのため、2回目の CSV を新たな測定結果として扱う前に、audited_at 列を確認してください。週次モニタリングは常に新しい監査を実行するので、時間の経過による変化を追うにはこちらのほうが適しています。
サイト全体ではなく、特定のページを監査できますか?
できます。入力ファイルにパスを含む完全な URL を書けば、それぞれが単一ページとして監査されます。ページ監査には、1時間あたりと1日あたりの独自の上限があります。上限に達すると API は 429 を返し、スクリプトは残りのページを API のメッセージとともに未監査として記録するので、それらのページは後で実行できます。サイト全体を見たい場合は、ホームページのアドレスを使ってください。
監査された URL が一覧のものと異なるのはなぜですか?
API は監査の前に、同じドメイン内にとどまるリダイレクトをたどります。そのため、example.com が www.example.com として監査されることがあります。別のドメインへのリダイレクトは黙ってたどることはせず、入力されたアドレスのまま監査し、リダイレクトを検出事項として報告します。自社の記録と突き合わせるには site 列を、結果を読むには audited_url 列を使ってください。
スクリプトの代わりに AI エージェントに実行させることはできますか?
できます。同じ API キーで、MCP に対応した任意のエージェントを MCP サーバーに接続できます。MCP サーバーは create_report、get_report_status、get_report を提供しています。設定方法はエージェントのセットアップガイドで説明しています。決まった一覧を定期的に処理するならスクリプトのほうが適しています。毎回まったく同じように動作し、比較できるファイルが残るからです。エージェントが向いているのは、1つのサイトの検出事項について追加の質問をしたい場合です。
CSV で、各サイトが Google にどうインデックス登録されたかはわかりますか?
わかりません。SEOReportは、監査の時点で各サイトが返した内容を外部から監査するもので、Search Console のデータは読み取りません。Google がある URL についてどう判断したかは Search Console で確認し、その原因となっていそうなサイト上の要素は検出事項で確認してください。