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 Audits (Pro/Ultra)

A deep, AI-assisted audit scoring a URL across 9 dimensions (~150 AI checks). It runs asynchronously — submit, then poll — 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)
status = seo.get_site_audit(job["job_id"], API_KEY)
# status["status"] -> queued | running | completed | failed
#   queued  -> {"queue_position", "eta_seconds"}
#   done    -> {"result"}

seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota

Deep audits require a Pro ($39/mo, 20/mo) or Ultra ($99/mo, 100/mo) key. Full engine reference: engine.seoscoreapi.com/docs.

Full Documentation

seoscoreapi.com/docs