seoscoreapi

Python client for SEO Score API — audit any URL for SEO issues with one function call.

Install

pip install seoscoreapi

Quick Start

from seoscoreapi import audit, signup

# Get a free API key (2 audits/day, no credit card)
key = signup("you@example.com")

# Run an audit
result = audit("https://example.com", api_key=key)
print(f"Score: {result['score']}/100 ({result['grade']})")

Functions

Historical tracking

Every audit on a paid plan returns a history block on the /audit response:

result = audit("https://example.com", api_key=key)
delta = result["history"].get("delta")
if delta:
    print(f"Score change: {delta['score']:+.1f} ({delta.get('grade_change') or 'no grade change'})")

Pull the full timeseries with history() or a one-shot per-domain summary with history_domains(). Retention windows: Starter 30 days, Basic 90 days, Pro 1 year, Ultra unlimited.

Webhook alerts on score drops

add_monitor(
    "https://example.com",
    api_key=key,
    frequency="daily",
    webhook_url="https://hooks.slack.com/services/T0/B0/xxxx",
    alert_threshold=5,
)

Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.

Deep Site Audit (Pro/Ultra, or credits)

A deep, AI-assisted audit scoring a URL across 9 dimensions (thousands of catalog checks plus up to 150 AI checks). It runs asynchronously, so start a job and poll it, or use deep_audit to block for the result:

import seoscoreapi as seo

# One call, waits for the result (handles the queue + backpressure for you):
result = seo.deep_audit(
    "https://yoursite.com", API_KEY,
    business_type="saas",                      # tunes which checks apply
    on_progress=lambda s: print(s["status"], s.get("queue_position", s.get("progress"))),
)
print(result["scores"]["lai_score"], result["scores"]["section_scores"])

# Or drive the job yourself:
job = seo.site_audit("https://yoursite.com", API_KEY)       # POST /site-audit
status = seo.get_site_audit(job["job_id"], API_KEY)         # GET  /site-audit/{job_id}
# status["status"] -> queued | running | completed | failed
#   queued    -> {"queue_position", "eta_seconds"}
#   completed -> {"result"}
result = seo.wait_for_site_audit(job["job_id"], API_KEY, timeout=600)

seo.deep_audit_usage(API_KEY)   # GET /deep-audit/usage -> {"site_audit": {"used", "remaining"}, ...}

Deep audits are included on Pro ($39/mo, 20/mo) and Ultra ($99/mo, 100/mo); any other key can run them on purchased credits.

Since 1.5.0 the SDK calls the main host, https://seoscoreapi.com, like every other endpoint. To point Deep Audit somewhere else (a proxy, staging, or the legacy engine.seoscoreapi.com host, which still works), pass base_url= to any Deep Audit function, assign seoscoreapi.DEEP_AUDIT_URL, or set SEOSCORE_DEEP_AUDIT_URL. engine_usage() is kept as an alias of deep_audit_usage().

Docs: seoscoreapi.com/docs (Deep Site Audit section).

Full Documentation

seoscoreapi.com/docs