seoscoreapi 1.1.0__tar.gz → 1.3.0__tar.gz

seoscoreapi-1.3.0/PKG-INFO

@@ -0,0 +1,88 @@
+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)

seoscoreapi-1.3.0/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 (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)

{seoscoreapi-1.1.0 → seoscoreapi-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seoscoreapi"
-version = "1.1.0"
+version = "1.3.0"
 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.3.0/seoscoreapi/__init__.py

@@ -0,0 +1,132 @@
+"""
+SEO Score API - Python Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Audit any URL for SEO issues with one function call.
+
+Usage:
+    from seoscoreapi import audit, signup
+
+    # Get a free API key
+    key = signup("you@example.com")
+
+    # Run an audit
+    result = audit("https://example.com", api_key=key)
+    print(f"Score: {result['score']}/100 ({result['grade']})")
+
+Full docs: https://seoscoreapi.com/docs
+"""
+
+from typing import Optional
+
+import requests
+
+BASE_URL = "https://seoscoreapi.com"
+__version__ = "1.3.0"
+
+_HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
+
+
+def signup(email: str) -> str:
+    """Sign up for a free API key. Returns the raw key (save it — shown only once)."""
+    r = requests.post(f"{BASE_URL}/signup", json={"email": email}, headers=_HEADERS)
+    r.raise_for_status()
+    return r.json()["api_key"]
+
+
+def audit(url: str, api_key: str) -> dict:
+    """Run an SEO audit on a URL. Returns score, grade, checks, and priorities."""
+    r = requests.get(f"{BASE_URL}/audit", params={"url": url}, headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()
+
+
+def batch_audit(urls: list[str], api_key: str) -> dict:
+    """Audit multiple URLs (paid plans only). Returns list of results."""
+    r = requests.post(f"{BASE_URL}/audit/batch", json={"urls": urls}, headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()
+
+
+def usage(api_key: str) -> dict:
+    """Check your API usage and limits."""
+    r = requests.get(f"{BASE_URL}/usage", headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()
+
+
+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()
+
+
+def list_monitors(api_key: str) -> list:
+    """List your active monitors."""
+    r = requests.get(f"{BASE_URL}/monitors", headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()["monitors"]
+
+
+def scoreboard_opt_out(api_key: str, opt_out: bool = True) -> dict:
+    """Opt in or out of the public SEO scoreboard."""
+    r = requests.put(f"{BASE_URL}/scoreboard/opt-out", params={"opt_out": str(opt_out).lower()}, headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    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})
+    r.raise_for_status()
+    return r.json()
+
+
+def report_url(domain: str) -> str:
+    """Get the shareable report URL for a domain."""
+    return f"{BASE_URL}/report/{domain}"
+
+
+def history(url: str, api_key: str, limit: int = 100, since: Optional[float] = None) -> dict:
+    """Get historical audit scores and trend summary for a URL (Starter plan or higher)."""
+    params: dict = {"url": url, "limit": limit}
+    if since is not None:
+        params["since"] = since
+    r = requests.get(f"{BASE_URL}/history", params=params, headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()
+
+
+def history_domains(api_key: str) -> list:
+    """List every domain audited by this key with latest score and 30-day trend (Starter plan or higher)."""
+    r = requests.get(f"{BASE_URL}/history/domains", headers={"X-API-Key": api_key, **_HEADERS})
+    r.raise_for_status()
+    return r.json()["domains"]

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

@@ -0,0 +1,88 @@
+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)

seoscoreapi-1.1.0/PKG-INFO

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: seoscoreapi
-Version: 1.1.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.1.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.1.0/seoscoreapi/__init__.py

@@ -1,79 +0,0 @@
-"""
-SEO Score API - Python Client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Audit any URL for SEO issues with one function call.
-
-Usage:
-    from seoscoreapi import audit, signup
-
-    # Get a free API key
-    key = signup("you@example.com")
-
-    # Run an audit
-    result = audit("https://example.com", api_key=key)
-    print(f"Score: {result['score']}/100 ({result['grade']})")
-
-Full docs: https://seoscoreapi.com/docs
-"""
-
-import requests
-
-BASE_URL = "https://seoscoreapi.com"
-__version__ = "1.1.0"
-
-_HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
-
-
-def signup(email: str) -> str:
-    """Sign up for a free API key. Returns the raw key (save it — shown only once)."""
-    r = requests.post(f"{BASE_URL}/signup", json={"email": email}, headers=_HEADERS)
-    r.raise_for_status()
-    return r.json()["api_key"]
-
-
-def audit(url: str, api_key: str) -> dict:
-    """Run an SEO audit on a URL. Returns score, grade, checks, and priorities."""
-    r = requests.get(f"{BASE_URL}/audit", params={"url": url}, headers={"X-API-Key": api_key, **_HEADERS})
-    r.raise_for_status()
-    return r.json()
-
-
-def batch_audit(urls: list[str], api_key: str) -> dict:
-    """Audit multiple URLs (paid plans only). Returns list of results."""
-    r = requests.post(f"{BASE_URL}/audit/batch", json={"urls": urls}, headers={"X-API-Key": api_key, **_HEADERS})
-    r.raise_for_status()
-    return r.json()
-
-
-def usage(api_key: str) -> dict:
-    """Check your API usage and limits."""
-    r = requests.get(f"{BASE_URL}/usage", headers={"X-API-Key": api_key, **_HEADERS})
-    r.raise_for_status()
-    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})
-    r.raise_for_status()
-    return r.json()
-
-
-def list_monitors(api_key: str) -> list:
-    """List your active monitors."""
-    r = requests.get(f"{BASE_URL}/monitors", headers={"X-API-Key": api_key, **_HEADERS})
-    r.raise_for_status()
-    return r.json()["monitors"]
-
-
-def scoreboard_opt_out(api_key: str, opt_out: bool = True) -> dict:
-    """Opt in or out of the public SEO scoreboard."""
-    r = requests.put(f"{BASE_URL}/scoreboard/opt-out", params={"opt_out": str(opt_out).lower()}, headers={"X-API-Key": api_key, **_HEADERS})
-    r.raise_for_status()
-    return r.json()
-
-
-def report_url(domain: str) -> str:
-    """Get the shareable report URL for a domain."""
-    return f"{BASE_URL}/report/{domain}"

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

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: seoscoreapi
-Version: 1.1.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)