seoscoreapi 1.2.0__tar.gz → 1.3.1__tar.gz

seoscoreapi-1.3.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: seoscoreapi
+Version: 1.3.1
+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 (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
+
+| 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)

seoscoreapi-1.3.1/README.md

@@ -0,0 +1,70 @@
+# 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 (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
+
+| 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)

{seoscoreapi-1.2.0 → seoscoreapi-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seoscoreapi"
-version = "1.2.0"
+version = "1.3.1"
 description = "Python client for SEO Score API — audit any URL for SEO issues with one function call"
 readme = "README.md"
 license = {text = "MIT"}

{seoscoreapi-1.2.0 → seoscoreapi-1.3.1}/seoscoreapi/__init__.py

@@ -22,7 +22,7 @@ from typing import Optional
 import requests
 
 BASE_URL = "https://seoscoreapi.com"
-__version__ = "1.2.0"
+__version__ = "1.3.1"
 
 _HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
 
@@ -55,9 +55,24 @@ def usage(api_key: str) -> dict:
     return r.json()
 
 
-def add_monitor(url: str, api_key: str, frequency: str = "daily") -> dict:
-    """Set up score monitoring for a URL (paid plans only)."""
-    r = requests.post(f"{BASE_URL}/monitors", json={"url": url, "frequency": frequency}, headers={"X-API-Key": api_key, **_HEADERS})
+def add_monitor(
+    url: str,
+    api_key: str,
+    frequency: str = "daily",
+    webhook_url: Optional[str] = None,
+    alert_threshold: int = 5,
+) -> dict:
+    """Set up score monitoring for a URL (paid plans only).
+
+    `webhook_url` (optional): receives a POST whenever the score drops
+    by `alert_threshold` points or more. Slack incoming-webhook URLs are
+    auto-formatted as Block Kit messages; any other https endpoint
+    receives the raw event JSON.
+    """
+    payload: dict = {"url": url, "frequency": frequency, "alert_threshold": alert_threshold}
+    if webhook_url:
+        payload["webhook_url"] = webhook_url
+    r = requests.post(f"{BASE_URL}/monitors", json=payload, headers={"X-API-Key": api_key, **_HEADERS})
     r.raise_for_status()
     return r.json()
 
@@ -76,6 +91,18 @@ def scoreboard_opt_out(api_key: str, opt_out: bool = True) -> dict:
     return r.json()
 
 
+def compare(urls: list[str], api_key: str) -> dict:
+    """Compare 2–5 URLs side by side with a structured diff (Basic plan or higher).
+
+    Returns each URL's score and category breakdown plus a `diff`
+    object describing who is ahead and by how much, per category and
+    per URL pair.
+    """
+    r = requests.post(f"{BASE_URL}/compare", json={"urls": urls}, headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()
+
+
 def competitive_audit(url: str, competitor_url: str, keyword: str, api_key: str) -> dict:
     """Run a head-to-head competitive audit (Pro plan or higher). Returns gap score, per-check diffs, and action items."""
     r = requests.post(f"{BASE_URL}/audit/competitive", json={"url": url, "competitor_url": competitor_url, "keyword": keyword}, headers={"X-API-Key": api_key, **_HEADERS})

seoscoreapi-1.3.1/seoscoreapi.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: seoscoreapi
+Version: 1.3.1
+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 (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
+
+| 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)

seoscoreapi-1.2.0/PKG-INFO

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: seoscoreapi
-Version: 1.2.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 multiple URLs (paid) |
-| `usage(api_key)` | Check usage and limits |
-| `add_monitor(url, api_key)` | Set up score monitoring (paid) |
-| `list_monitors(api_key)` | List active monitors |
-| `report_url(domain)` | Get shareable report URL |
-
-## Full Documentation
-
-[seoscoreapi.com/docs](https://seoscoreapi.com/docs)

seoscoreapi-1.2.0/README.md

@@ -1,38 +0,0 @@
-# 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 multiple URLs (paid) |
-| `usage(api_key)` | Check usage and limits |
-| `add_monitor(url, api_key)` | Set up score monitoring (paid) |
-| `list_monitors(api_key)` | List active monitors |
-| `report_url(domain)` | Get shareable report URL |
-
-## Full Documentation
-
-[seoscoreapi.com/docs](https://seoscoreapi.com/docs)

seoscoreapi-1.2.0/seoscoreapi.egg-info/PKG-INFO

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: seoscoreapi
-Version: 1.2.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 multiple URLs (paid) |
-| `usage(api_key)` | Check usage and limits |
-| `add_monitor(url, api_key)` | Set up score monitoring (paid) |
-| `list_monitors(api_key)` | List active monitors |
-| `report_url(domain)` | Get shareable report URL |
-
-## Full Documentation
-
-[seoscoreapi.com/docs](https://seoscoreapi.com/docs)