Metadata-Version: 2.4
Name: seoscoreapi
Version: 1.3.0
Summary: Python client for SEO Score API — audit any URL for SEO issues with one function call
Author-email: SEO Score API <info@seoscoreapi.com>
License: MIT
Project-URL: Homepage, https://seoscoreapi.com
Project-URL: Documentation, https://seoscoreapi.com/docs
Project-URL: Repository, https://github.com/avansledright/seoscoreapi.com
Keywords: seo,audit,api,seo-score,website-audit,seo-checker
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20

# seoscoreapi

Python client for [SEO Score API](https://seoscoreapi.com) — audit any URL for SEO issues with one function call.

## Install

```bash
pip install seoscoreapi
```

## Quick Start

```python
from seoscoreapi import audit, signup

# Get a free API key (5 audits/day)
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

| Function | Description |
|---|---|
| `signup(email)` | Get a free API key |
| `audit(url, api_key)` | Run SEO audit on a URL |
| `batch_audit(urls, api_key)` | Audit up to 10 URLs in one call (paid) |
| `compare(urls, api_key)` | Compare 2–5 URLs with a structured diff (Basic+) |
| `competitive_audit(url, competitor_url, keyword, api_key)` | Head-to-head audit with gap score (Pro+) |
| `history(url, api_key, limit=100, since=None)` | Full audit timeseries + summary for a URL (Starter+) |
| `history_domains(api_key)` | Every domain audited by this key with latest score and 30-day trend (Starter+) |
| `usage(api_key)` | Check usage and limits |
| `add_monitor(url, api_key, frequency="daily", webhook_url=None, alert_threshold=5)` | Set up score monitoring with optional Slack/webhook alerts (paid) |
| `list_monitors(api_key)` | List active monitors |
| `scoreboard_opt_out(api_key, opt_out=True)` | Opt in or out of the public scoreboard |
| `report_url(domain)` | Get shareable report URL |

## Historical tracking

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

```python
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

```python
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.

## Full Documentation

[seoscoreapi.com/docs](https://seoscoreapi.com/docs)
