SEO report API in Python: audit a site and read the findings

#!/usr/bin/env python3
"""Audit one site with the SEOReport API and print its top three fixes.

Usage: SEOREPORT_API_KEY=... python3 recipe.py [https://example.com]
Standard library only: nothing to install.
"""
import json
import os
import sys
import time
import urllib.error
import urllib.request

API = "https://seoreport.dev/api/v1/reports"
MAX_WAIT_SECONDS = 300  # stop waiting after five minutes
DEFAULT_POLL_MS = 5000  # used only when the API sends no pollAfterMs
TERMINAL_FAILURES = {"failed", "dead_lettered", "cancelled"}


class ApiRefusal(Exception):
    pass


def request(method, url, key, body=None):
    """Send one request; return (status, headers, raw bytes) for any HTTP status."""
    data = json.dumps(body).encode("utf-8") if body is not None else None
    req = urllib.request.Request(url, data=data, method=method)
    req.add_header("Authorization", "Bearer " + key)
    req.add_header("Accept", "application/json")
    req.add_header("User-Agent", "seoreport-recipe-python/1")
    if data is not None:
        req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return resp.status, resp.headers, resp.read()
    except urllib.error.HTTPError as err:
        return err.code, err.headers, err.read()


def parse(status, raw):
    try:
        return json.loads(raw.decode("utf-8"))
    except ValueError:
        raise ApiRefusal(f"HTTP {status}: not JSON: {raw[:200]!r}")


def refuse(status, headers, payload):
    """Turn an error response into one line that names the API's own code."""
    code = payload.get("code") or payload.get("errorCode") or f"HTTP_{status}"
    line = f"{code} (HTTP {status}): {payload.get('error', 'no message')}"
    if payload.get("ctaUrl"):
        line += f" -> https://seoreport.dev{payload['ctaUrl']}"
    retry_after = headers.get("Retry-After") if headers else None
    if retry_after:
        line += f" [retry after {retry_after}s]"
    raise ApiRefusal(line)


def main():
    key = os.environ.get("SEOREPORT_API_KEY", "").strip()
    if not key:
        print("Set SEOREPORT_API_KEY to an API key from your SEOReport plan.", file=sys.stderr)
        sys.exit(2)
    target = sys.argv[1] if len(sys.argv) > 1 else "https://example.com"

    # 1. Create the report (or reuse the one this account already has).
    status, headers, raw = request("POST", API, key, {"url": target})
    created = parse(status, raw)
    if status >= 400 or not created.get("success"):
        refuse(status, headers, created)
    job_id = created["report"]["jobId"]
    state = created["report"]["status"]
    poll_ms = created.get("pollAfterMs") or DEFAULT_POLL_MS
    print(f"job {job_id}: {state}")

    # 2. Poll politely until the job leaves queued/running, with a hard cap.
    deadline = time.monotonic() + MAX_WAIT_SECONDS
    job = created
    while state in ("queued", "running"):
        if time.monotonic() + poll_ms / 1000 > deadline:
            raise ApiRefusal(f"gave up after {MAX_WAIT_SECONDS}s; job {job_id} is still {state}")
        time.sleep(poll_ms / 1000)
        status, headers, raw = request("GET", f"{API}/{job_id}", key)
        job = parse(status, raw)
        if status >= 400 or not job.get("success"):
            refuse(status, headers, job)
        state = job["report"]["status"]
        if job.get("stuck"):
            raise ApiRefusal(f"job {job_id} stopped making progress; start a new report")
        poll_ms = job.get("pollAfterMs") or DEFAULT_POLL_MS

    if state != "completed":
        err = job.get("error") or {}
        detail = f"{err.get('code', state)}: {err.get('message', '')}".strip()
        retry = " (retryable)" if err.get("retryable") else ""
        raise ApiRefusal(f"report {state}: {detail}{retry}")

    # 3. Download the JSON diagnosis and keep a copy.
    status, headers, raw = request("GET", f"{API}/{job_id}/download?format=json", key)
    report = parse(status, raw)
    if status >= 400:
        refuse(status, headers, report)
    path = f"seoreport-{job_id}.json"
    with open(path, "wb") as fh:
        fh.write(raw)

    # 4. Print the score, the band and the first three open findings.
    score = report["score"]
    print(f"{report['targetUrl']}: {score['overall']}/100 ({score['band']})")
    print(f"open issues: {report['openIssues']['total']}, pages analysed: {report['pagesAnalyzed']}")
    open_findings = [f for f in report["findings"] if f["status"] in ("fail", "warn")]
    for finding in open_findings[:3]:
        severity = finding["severity"] or finding["status"]
        print(f"\n#{finding['rank']} [{severity}] {finding['title']} ({finding['area']['name']})")
        print(f"   Fix: {finding['fix']}")
    if report.get("message"):
        print(report["message"])
    print(f"\nfull diagnosis saved to {path}")


if __name__ == "__main__":
    try:
        main()
    except ApiRefusal as refusal:
        sys.exit(f"SEOReport: {refusal}")
    except urllib.error.URLError as err:
        sys.exit(f"network error: {err.reason}")

job 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18: queued
https://example.com: 64/100 (mixed)
open issues: 9, pages analysed: 24

#1 [high] Canonical tag missing (URLs & Redirects)
   Fix: Add a canonical link element or Link HTTP header pointing to the preferred URL for this page. This is a strong canonicalization signal that helps search systems understand which version represents duplicate or very similar content; the declared URL remains a preference, not a guarantee.

#2 [high] Meta description missing (On-Page SEO)
   Fix: Add a concise, page-specific meta description that accurately describes the visible content. Search systems may use it for a result snippet when it is more helpful than text taken from the page.

#3 [high] Render parity mismatch (Crawl & Index)
   Fix: Ensure raw HTML and rendered DOM contain the same critical SEO elements (title, H1, canonical, meta description, structured data). If content is injected by JavaScript, move it to server-side rendering so crawlers see it immediately.

full diagnosis saved to seoreport-3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18.json