API d'audit SEO en Python : auditer une liste de sites, exporter en CSV
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 :
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 :
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 :
example.comexample.orgshop.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
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 avertissementL'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 ».
"""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"
Chaque code de réponse géré a une signification différente pour un lot :
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.
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
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 :
targetUrlest 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 verswww, l'audit suit la redirection : conservez donc à la fois votre entrée et cette valeur.auditedAtindique quand l'audit a eu lieu ; le script l'écrit dans la colonneaudited_at.score.overallest le score de 0 à 100 de ce site ce jour-là.view.sectionsest la liste des sections du rapport. Celle dont lakeyvautfull_findingscontientdetail.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.
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])
Lancez-le avec la liste d'entrée et un chemin de sortie :
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.
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 :
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}")
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.
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.