Back to articles

API d'audit SEO en Python : auditer une liste de sites, exporter en CSV

SEOReport Team·
apipythonautomationseo-auditcsv-export

Un script Python opérationnel pour l'API d'audit SEO de SEOReport : envoyer une liste de sites, interroger chaque rapport jusqu'à ce qu'il soit prêt, tout exporter en CSV.

Pour auditer une liste de sites depuis Python, il vous faut trois appels à l'API REST de SEOReport par site : créer un rapport, interroger son statut jusqu'à ce qu'il ne soit plus en file d'attente ni en cours, puis lire le résultat final. Le script ci-dessous le fait pour une simple liste de domaines au format texte : il garde quelques rapports en cours en parallèle, attend entre deux interrogations aussi longtemps que l'API le demande, et produit une ligne CSV par constat en échec ou en avertissement. Il nécessite Python 3.8 ou ultérieur, le paquet requests et une clé API associée à un abonnement payant.

Chaque endpoint et chaque champ utilisés ici figurent sur la page développeurs et dans la référence de l'API, ou font partie du JSON renvoyé par l'endpoint de résultat. Les noms de champs ont été vérifiés sur ce contenu en octobre 2026.

Ce qu'il vous faut avant la première requête

L'accès à l'API est lié à un compte. Vous créez une clé dans les paramètres de votre compte dès que vous avez un abonnement, et la même clé fonctionne pour l'API REST et pour le serveur MCP. Chaque requête l'envoie sous forme de jeton Bearer :

http
Authorization: Bearer YOUR_API_KEY

Ne mettez pas la clé dans le script. Exportez-la dans une variable d'environnement et lisez-la au démarrage :

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

Deux règles sur les crédits orientent la construction de la liste. Chaque nouveau site audité via l'API consomme un crédit de votre abonnement, exactement comme sur le site web. Relancer un site pour lequel vous avez déjà un rapport n'en consomme pas d'autre. Avant un gros lot, comparez le nombre de nouveaux sites de la liste avec les crédits restants de votre abonnement ; le script cesse d'envoyer des sites quand les crédits sont épuisés et exporte quand même ce qui est terminé, mais mieux vaut le savoir à l'avance.

L'entrée est un fichier texte avec un site par ligne :

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

Envoyez chaque site sous la forme de l'adresse de sa page d'accueil. L'API lit l'URL que vous envoyez : un domaine nu ou une page d'accueil donne lieu à un audit de site couvrant la page d'accueil, les pages listées dans son sitemap et celles vers lesquelles pointent ses liens internes, tandis qu'une URL avec un chemin n'audite que cette page. Pour un portefeuille de sites, ce sont des domaines nus qu'il vous faut.

Comment les appels s'enchaînent

loop[Tant que le statut est queued ou running]POST /api/v1/reports avec l'URL du sitereport.jobId et report.statusGET /api/v1/reports/jobIdreport.status et pollAfterMsGET /api/v1/reports/jobId/resultscore et constats completsAjoute au CSV les constats en échec et en avertissementScript PythonAPI SEOReportScript PythonAPI SEOReport
Diagram source
sequenceDiagram
    participant S as Script Python
    participant A as API SEOReport
    S->>A: POST /api/v1/reports avec l'URL du site
    A-->>S: report.jobId et report.status
    loop Tant que le statut est queued ou running
        S->>A: GET /api/v1/reports/jobId
        A-->>S: report.status et pollAfterMs
    end
    S->>A: GET /api/v1/reports/jobId/result
    A-->>S: score et constats complets
    S->>S: Ajoute au CSV les constats en échec et en avertissement

L'appel d'envoi répond rapidement avec un identifiant de tâche (job ID). L'appel de statut vous indique où en est le rapport : queued, running, puis completed ou failed. Chaque réponse de statut contient aussi pollAfterMs, le nombre de millisecondes que l'API vous suggère d'attendre avant de redemander. Tant qu'un rapport est en cours, c'est quelques secondes, et la valeur tombe à 0 quand le rapport est terminé. La plupart des rapports se terminent en moins d'une minute.

Étape 1 : envoyer chaque site et gérer les refus

La fonction d'envoi transmet l'URL et renvoie l'identifiant de tâche. Elle décide aussi quoi faire quand l'API refuse, car un script de traitement par lots doit distinguer « ralentissez » de « arrêtez » et de « passez celui-ci ».

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"

Chaque code de réponse géré a une signification différente pour un lot :

201503402429, ou autre erreurPOST /api/v1/reportsCode HTTPGarder report.jobId etcommencer à interrogerAttendre, puis renvoyer,jusqu'à 3 essaisCrédits épuisés ou pasd'abonnement : cesser lesenvoisConsigner l'erreur pour cesite et continuer
Diagram source
flowchart TD
    A["POST /api/v1/reports"] --> B{"Code HTTP"}
    B -->|201| C["Garder report.jobId et commencer à interroger"]
    B -->|503| D["Attendre, puis renvoyer, jusqu'à 3 essais"]
    B -->|402| E["Crédits épuisés ou pas d'abonnement : cesser les envois"]
    B -->|"429, ou autre erreur"| F["Consigner l'erreur pour ce site et continuer"]

Un 402 signifie que le compte ne peut pas lancer de nouveau site pour le moment : tous les envois suivants échoueraient de la même manière. Le script cesse d'envoyer, laisse se terminer les rapports déjà en cours et marque le reste de la liste comme non audité avec le message de l'API ; le CSV contient ainsi tout ce qui a abouti. Un 503 signifie que le service n'a pas pu prendre le rapport à ce moment-là : le script attend et renvoie le même site, en respectant l'en-tête Retry-After quand l'API l'envoie et en attendant 30 secondes sinon ; après 3 refus, il consigne le site et continue. Un 429 n'est pas retenté. Quand il vient d'une limite d'audits de pages, son code indique laquelle, PAGE_AUDIT_HOURLY_LIMIT ou PAGE_AUDIT_DAILY_LIMIT, et son en-tête Retry-After donne le nombre de secondes avant qu'elle ne soit levée, ce qui peut représenter près d'une heure ou près d'une journée : le script consigne donc le message et passe au suivant au lieu d'attendre. Tout autre cas, comme une adresse qui n'est pas un site web public valide, est propre à ce site : le script le consigne et passe au suivant.

Étape 2 : interroger avec mesure et garder quelques rapports en cours

Envoyer 50 sites d'un coup, puis interroger les 50 chaque seconde : c'est le schéma à éviter. La fonction ci-dessous garde au plus IN_FLIGHT rapports en cours, marque une pause entre deux envois et attend, entre deux tours d'interrogation, l'intervalle suggéré par l'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

Considérez tout statut autre que queued et running comme définitif, et seul completed comme un succès. MAX_WAIT est un garde-fou, pas une durée attendue : la plupart des rapports se terminent bien avant, et il sert seulement à empêcher un rapport qui ne se termine jamais de bloquer tout le lot. Quand une exécution échoue, la réponse de statut contient un objet error avec un code, un message et un indicateur retryable. Des codes comme DNS_FAILURE, CRAWLER_BLOCKED et TLS_ERROR décrivent le site lui-même : le domaine ne se résout pas, une règle anti-bot a refusé la requête, ou la connexion sécurisée a échoué. Réessayer donne la même réponse, et cette réponse mérite en soi d'être portée à la connaissance du propriétaire du site. Notre recette pour un pipeline CI utilise le même objet error pour distinguer un déploiement défaillant d'un audit qui n'a pas pu s'exécuter.

Étape 3 : lire les constats et écrire le CSV

Une fois le rapport terminé, GET /api/v1/reports/{id}/result renvoie le résultat complet. Dans report, quatre éléments comptent pour l'export :

  • targetUrl est l'adresse réellement auditée. Si votre entrée redirige vers un autre hôte du même domaine, par exemple du domaine nu vers www, l'audit suit la redirection : conservez donc à la fois votre entrée et cette valeur.
  • auditedAt indique quand l'audit a eu lieu ; le script l'écrit dans la colonne audited_at.
  • score.overall est le score de 0 à 100 de ce site ce jour-là.
  • view.sections est la liste des sections du rapport. Celle dont la key vaut full_findings contient detail.findings, un objet par constat.

Chaque constat comporte un status (fail, warn, pass ou info), un areaLabel qui nomme la partie du site concernée, un title, une explication whyItMatters et, pour les constats en échec ou en avertissement, un fix. Le texte est dans la langue du rapport. Les preuves propres au site, comme les URL concernées, se trouvent dans le rapport complet et non dans ces champs : c'est pourquoi la dernière section de cet article en enregistre une copie à côté du 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])

Lancez-le avec la liste d'entrée et un chemin de sortie :

bash
python audit_sites.py sites.txt findings.csv

Les sites en erreur restent dans le fichier. Un site qui n'a pas pu être audité reçoit une ligne not_audited avec la raison dans note, et un rapport terminé dont les constats n'ont pas pu être lus reçoit une ligne unreadable. Filtrez sur ces deux valeurs avant de partager le fichier : un CSV qui aurait omis un site sans le signaler ferait passer ce site pour un site sans problème.

Combien de lignes attendre

Attendez-vous à des lignes pour presque chaque site. Sur 249 sites externes audités par SEOReport entre le 23 août et le 4 octobre 2026, le rapport médian signalait 14 problèmes distincts (constats en échec ou en avertissement) ; un quart des sites en comptait 17 ou plus, et aucun n'en avait zéro.

Problèmes signalés par site, 249 sites externes, août–oct. 2026

En multipliant cette médiane par la longueur de votre liste, vous obtenez une première estimation raisonnable de la taille du fichier : une liste de 40 sites proches de la médiane donne environ 560 lignes. C'est trop pour une lecture ligne par ligne, d'où les colonnes area et finding. Triez sur finding et les problèmes récurrents dans tout le portefeuille ressortent ensemble :

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}")

Quand un même constat échoue sur 12 sites sur 40, cherchez d'abord une cause commune : un thème, une extension ou un template d'hébergement partagé peut transformer 12 problèmes en 1 correction appliquée 12 fois. La comparaison tient parce que chaque site du fichier a été vérifié avec la même méthode, et la colonne audited_at indique quand. Couvrir le même terrain en chat avec une IA demande de nombreuses conversations distinctes, qui repartent chacune de zéro ; ce calcul pour un site de 500 pages en fait le compte.

Conservez le rapport complet à côté du CSV

Le CSV est une vue de travail. Pour l'archivage, ou pour envoyer le diagnostic complet au propriétaire d'un site, téléchargez chaque rapport au format voulu : pdf, md, txt ou 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)

Le PDF contient une page de couverture, la synthèse générée par IA, la répartition par catégorie et l'ensemble des constats. Notre présentation du contenu d'un rapport noté explique comment lire chaque partie.

Pour continuer à suivre les mêmes sites après le premier export, inscrivez-les à la surveillance hebdomadaire avec PUT /api/v1/monitors, en envoyant {"url": ..., "alertEmail": ...} pour chacun. La surveillance est incluse dans les abonnements payants, ne consomme pas de crédits de rapport, et n'écrit à l'adresse d'alerte que lorsqu'un nouveau constat critique ou de gravité élevée apparaît, qu'un constat critique est résolu, ou que le score change de tranche.

Questions fréquentes

Relancer le script consomme-t-il de nouveaux crédits ?

Pas pour les sites dont vous avez déjà un rapport. Quand un site a déjà un rapport, l'API peut renvoyer ce rapport existant au lieu de lancer un nouvel audit : vérifiez donc la colonne audited_at avant de considérer un second CSV comme une nouvelle mesure. La surveillance hebdomadaire lance toujours un nouvel audit, ce qui en fait le meilleur outil pour suivre l'évolution dans le temps.

Puis-je auditer des pages précises plutôt que des sites entiers ?

Oui. Mettez des URL complètes, avec leur chemin, dans le fichier d'entrée : chacune sera auditée comme une page isolée. Les audits de pages ont leurs propres limites horaire et journalière. Quand vous en atteignez une, l'API répond 429 et le script marque chaque page restante comme non auditée avec le message de l'API, pour que vous puissiez les relancer plus tard. Pour une vue de l'ensemble d'un site, utilisez les adresses des pages d'accueil.

Pourquoi l'URL auditée diffère-t-elle de celle de ma liste ?

Avant l'audit, l'API suit une redirection qui reste sur le même domaine : example.com peut donc être audité sous la forme www.example.com. Une redirection vers un autre domaine n'est pas suivie en silence : l'audit conserve votre adresse et signale la redirection comme un constat. Utilisez la colonne site pour les rapprochements avec vos propres données et audited_url pour lire les résultats.

Un agent IA peut-il faire ce travail à la place d'un script ?

Oui. La même clé API connecte n'importe quel agent compatible MCP au serveur MCP, qui propose create_report, get_report_status et get_report ; notre guide de configuration pour les agents détaille la mise en place. Un script convient mieux à une liste fixe traitée à intervalles réguliers, car il s'exécute à l'identique à chaque fois et produit un fichier comparable. Un agent est préférable quand quelqu'un veut poser des questions de suivi sur les constats d'un site.

Le CSV montre-t-il comment Google a indexé chaque site ?

Non. SEOReport audite, de l'extérieur, ce que chaque site servait au moment de l'audit, et ne lit pas les données de la Search Console. Utilisez la Search Console pour voir ce que Google a décidé pour une URL, et les constats pour voir ce qui, sur le site, peut en être la cause.

Obtenez le diagnostic complet de votre site

Un rapport fondé sur des preuves et un plan d’action priorisé, avec une offre à crédits mensuels.