diff --git a/web/src/padelnomics/admin/templates/admin/partials/seo_funnel.html b/web/src/padelnomics/admin/templates/admin/partials/seo_funnel.html
new file mode 100644
index 0000000..ece0800
--- /dev/null
+++ b/web/src/padelnomics/admin/templates/admin/partials/seo_funnel.html
@@ -0,0 +1,96 @@
+
+
+
+{% set max_val = [funnel.impressions, funnel.clicks, funnel.pageviews, funnel.visitors, funnel.planner_users, funnel.leads] | max or 1 %}
+
+
+
Search (GSC + Bing)
+
+
+
ImpressionsSearch results shown
+
+
+ {{ "{:,}".format(funnel.impressions | int) }}
+
+
+
+
+
ClicksCTR: {{ "%.1f" | format(funnel.ctr * 100) }}%
+
+
+ {{ "{:,}".format(funnel.clicks | int) }}
+
+
+
+
Analytics (Umami)
+
+
+
Pageviews{% if funnel.clicks %}{{ "%.0f" | format(funnel.click_to_view * 100) }}% of clicks{% endif %}
+
+
+ {{ "{:,}".format(funnel.pageviews | int) }}
+
+
+
+
+
VisitorsUnique
+
+
+ {{ "{:,}".format(funnel.visitors | int) }}
+
+
+
+
Conversions (App)
+
+
+
Planner Users{% if funnel.visitors %}{{ "%.1f" | format(funnel.visitor_to_planner * 100) }}% of visitors{% endif %}
+
+
+ {{ "{:,}".format(funnel.planner_users | int) }}
+
+
+
+
+
Lead Requests{% if funnel.planner_users %}{{ "%.1f" | format(funnel.planner_to_lead * 100) }}% of planners{% endif %}
+
+
+ {{ "{:,}".format(funnel.leads | int) }}
+
+
+
+
No funnel data yet. Run a sync to populate search and analytics metrics.
+
+
+
+
+ | Title |
+ Impressions |
+ Clicks |
+ CTR |
+ Pos |
+ Views |
+ Bounce |
+ Published |
+ Flags |
+
+
+
+ {% for a in scorecard %}
+
+
+ {{ a.title or a.url_path }}
+ {% if a.template_slug %}
+
{{ a.template_slug }}
+ {% endif %}
+ |
+ {{ "{:,}".format(a.impressions | int) }} |
+ {{ "{:,}".format(a.clicks | int) }} |
+ {{ "%.1f" | format((a.ctr or 0) * 100) }}% |
+ {{ "%.1f" | format(a.position_avg or 0) }} |
+ {{ "{:,}".format(a.pageviews | int) }} |
+
+ {% if a.bounce_rate is not none %}{{ "%.0f" | format(a.bounce_rate * 100) }}%{% else %}-{% endif %}
+ |
+ {{ a.published_at[:10] if a.published_at else '-' }} |
+
+ {% if a.flag_low_ctr %}
+ Low CTR
+ {% endif %}
+ {% if a.flag_no_clicks %}
+ No Clicks
+ {% endif %}
+ |
+
+ {% endfor %}
+
+
+
{{ scorecard | length }} articles shown
+{% else %}
+
+
No published articles match the current filters, or no search/analytics data synced yet.
+
+
+
+
+
+
+
+
+
+ Top Queries
+ {% if queries %}
+
+
+
+
+ | Query |
+ Impressions |
+ Clicks |
+ CTR |
+ Pos |
+
+
+
+ {% for q in queries[:20] %}
+
+ | {{ q.query }} |
+ {{ "{:,}".format(q.impressions | int) }} |
+ {{ "{:,}".format(q.clicks | int) }} |
+ {{ "%.1f" | format((q.ctr or 0) * 100) }}% |
+ {{ "%.1f" | format(q.position_avg or 0) }} |
+
+ {% endfor %}
+
+
+
+
No query data yet. Run a sync to populate.
+
+
+
+
+ Top Pages
+ {% if pages %}
+
+
+
+
+ | Page |
+ Impressions |
+ Clicks |
+ CTR |
+ Pos |
+
+
+
+ {% for p in pages[:20] %}
+
+ | {{ p.page_url }} |
+ {{ "{:,}".format(p.impressions | int) }} |
+ {{ "{:,}".format(p.clicks | int) }} |
+ {{ "%.1f" | format((p.ctr or 0) * 100) }}% |
+ {{ "%.1f" | format(p.position_avg or 0) }} |
+
+ {% endfor %}
+
+
+
+
+
+
+ By Country
+ {% if countries %}
+
+
+ | Country | Impressions | Clicks |
|---|
+
+ {% for c in countries[:15] %}
+
+ | {{ c.country | upper }} |
+ {{ "{:,}".format(c.impressions | int) }} |
+ {{ "{:,}".format(c.clicks | int) }} |
+
+ {% endfor %}
+
+
+
+
+
+
+ By Device (GSC)
+ {% if devices %}
+
+
+ | Device | Impressions | Clicks |
|---|
+
+ {% for d in devices %}
+
+ | {{ d.device | capitalize }} |
+ {{ "{:,}".format(d.impressions | int) }} |
+ {{ "{:,}".format(d.clicks | int) }} |
+
+ {% endfor %}
+
+
+
No device data (GSC only).
+
+ Last sync:
+ {% for s in sync_status %}
+
+ {{ s.source | upper }}
+ {% if s.status == 'success' %}
+ {{ s.completed_at[:16] if s.completed_at else '' }} ({{ s.rows_synced }} rows)
+ {% elif s.status == 'failed' %}
+ failed
+ {% endif %}
+
+ {% endfor %}
+ {% if not sync_status %}
+ No syncs yet
+ {% endif %}
+
+
+
+
+
+ {% for d, label in [(7, '7d'), (28, '28d'), (90, '3m'), (180, '6m'), (365, '12m')] %}
+
+ {% endfor %}
+
+
+
+
Impressions
+
{{ "{:,}".format(overview.total_impressions | int) }}
+
+
+
Clicks
+
{{ "{:,}".format(overview.total_clicks | int) }}
+
+
+
Avg CTR
+
{{ "%.1f" | format(overview.avg_ctr * 100) }}%
+
+
+
Avg Position
+
{{ "%.1f" | format(overview.avg_position) }}
+
+
+
+
+
+
+
+
+
+
+
+{% endblock %}
diff --git a/web/src/padelnomics/core.py b/web/src/padelnomics/core.py
index a85e368..4d52e4e 100644
--- a/web/src/padelnomics/core.py
+++ b/web/src/padelnomics/core.py
@@ -54,6 +54,12 @@ class Config:
UMAMI_API_TOKEN: str = os.getenv("UMAMI_API_TOKEN", "")
UMAMI_WEBSITE_ID: str = "4474414b-58d6-4c6e-89a1-df5ea1f49d70"
+ # SEO metrics sync
+ GSC_SERVICE_ACCOUNT_PATH: str = os.getenv("GSC_SERVICE_ACCOUNT_PATH", "")
+ GSC_SITE_URL: str = os.getenv("GSC_SITE_URL", "")
+ BING_WEBMASTER_API_KEY: str = os.getenv("BING_WEBMASTER_API_KEY", "")
+ BING_SITE_URL: str = os.getenv("BING_SITE_URL", "")
+
RESEND_API_KEY: str = os.getenv("RESEND_API_KEY", "")
EMAIL_FROM: str = _env("EMAIL_FROM", "hello@padelnomics.io")
LEADS_EMAIL: str = _env("LEADS_EMAIL", "leads@padelnomics.io")
diff --git a/web/src/padelnomics/migrations/versions/0019_add_seo_metrics.py b/web/src/padelnomics/migrations/versions/0019_add_seo_metrics.py
new file mode 100644
index 0000000..aea6400
--- /dev/null
+++ b/web/src/padelnomics/migrations/versions/0019_add_seo_metrics.py
@@ -0,0 +1,84 @@
+"""Add SEO metrics tables for GSC, Bing, and Umami data sync.
+
+Three tables:
+ - seo_search_metrics — daily search data per page+query (GSC + Bing)
+ - seo_analytics_metrics — daily page analytics (Umami)
+ - seo_sync_log — tracks sync state per source
+"""
+
+
+def up(conn):
+ # ── 1. Search metrics (GSC + Bing) ─────────────────────────────────
+ conn.execute("""
+ CREATE TABLE IF NOT EXISTS seo_search_metrics (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ source TEXT NOT NULL,
+ metric_date TEXT NOT NULL,
+ page_url TEXT NOT NULL,
+ query TEXT,
+ country TEXT,
+ device TEXT,
+ clicks INTEGER NOT NULL DEFAULT 0,
+ impressions INTEGER NOT NULL DEFAULT 0,
+ ctr REAL,
+ position_avg REAL,
+ created_at TEXT NOT NULL DEFAULT (datetime('now'))
+ )
+ """)
+ # COALESCE converts NULLs to '' for unique index (SQLite treats
+ # NULL as distinct in UNIQUE constraints, causing duplicate rows)
+ conn.execute("""
+ CREATE UNIQUE INDEX IF NOT EXISTS idx_seo_search_dedup
+ ON seo_search_metrics(
+ source, metric_date, page_url,
+ COALESCE(query, ''), COALESCE(country, ''), COALESCE(device, '')
+ )
+ """)
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_seo_search_date"
+ " ON seo_search_metrics(metric_date)"
+ )
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_seo_search_page"
+ " ON seo_search_metrics(page_url)"
+ )
+
+ # ── 2. Analytics metrics (Umami) ───────────────────────────────────
+ conn.execute("""
+ CREATE TABLE IF NOT EXISTS seo_analytics_metrics (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ metric_date TEXT NOT NULL,
+ page_url TEXT NOT NULL,
+ pageviews INTEGER NOT NULL DEFAULT 0,
+ visitors INTEGER NOT NULL DEFAULT 0,
+ bounce_rate REAL,
+ time_avg_seconds INTEGER,
+ created_at TEXT NOT NULL DEFAULT (datetime('now'))
+ )
+ """)
+ conn.execute("""
+ CREATE UNIQUE INDEX IF NOT EXISTS idx_seo_analytics_dedup
+ ON seo_analytics_metrics(metric_date, page_url)
+ """)
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_seo_analytics_date"
+ " ON seo_analytics_metrics(metric_date)"
+ )
+
+ # ── 3. Sync log ────────────────────────────────────────────────────
+ conn.execute("""
+ CREATE TABLE IF NOT EXISTS seo_sync_log (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ source TEXT NOT NULL,
+ status TEXT NOT NULL,
+ rows_synced INTEGER NOT NULL DEFAULT 0,
+ error TEXT,
+ started_at TEXT NOT NULL,
+ completed_at TEXT,
+ duration_ms INTEGER
+ )
+ """)
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_seo_sync_source"
+ " ON seo_sync_log(source, started_at)"
+ )
diff --git a/web/src/padelnomics/seo/__init__.py b/web/src/padelnomics/seo/__init__.py
new file mode 100644
index 0000000..40a4e2b
--- /dev/null
+++ b/web/src/padelnomics/seo/__init__.py
@@ -0,0 +1,36 @@
+"""
+SEO metrics sync and query module.
+
+Syncs data from Google Search Console, Bing Webmaster Tools, and Umami
+into SQLite tables. Query functions support the admin SEO hub views.
+"""
+
+from ._bing import sync_bing
+from ._gsc import sync_gsc
+from ._queries import (
+ cleanup_old_metrics,
+ get_article_scorecard,
+ get_country_breakdown,
+ get_device_breakdown,
+ get_funnel_metrics,
+ get_search_performance,
+ get_sync_status,
+ get_top_pages,
+ get_top_queries,
+)
+from ._umami import sync_umami
+
+__all__ = [
+ "sync_gsc",
+ "sync_bing",
+ "sync_umami",
+ "get_search_performance",
+ "get_top_queries",
+ "get_top_pages",
+ "get_country_breakdown",
+ "get_device_breakdown",
+ "get_funnel_metrics",
+ "get_article_scorecard",
+ "get_sync_status",
+ "cleanup_old_metrics",
+]
diff --git a/web/src/padelnomics/seo/_bing.py b/web/src/padelnomics/seo/_bing.py
new file mode 100644
index 0000000..5a76446
--- /dev/null
+++ b/web/src/padelnomics/seo/_bing.py
@@ -0,0 +1,142 @@
+"""Bing Webmaster Tools sync via REST API.
+
+Uses an API key for auth. Fetches query stats and page stats.
+"""
+
+from datetime import datetime, timedelta
+from urllib.parse import urlparse
+
+import httpx
+
+from ..core import config, execute
+
+_TIMEOUT_SECONDS = 30
+
+
+def _normalize_url(full_url: str) -> str:
+ """Strip a full URL to just the path."""
+ parsed = urlparse(full_url)
+ return parsed.path or "/"
+
+
+async def sync_bing(days_back: int = 3, timeout_seconds: int = _TIMEOUT_SECONDS) -> int:
+ """Sync Bing Webmaster query stats into seo_search_metrics. Returns rows synced."""
+ assert 1 <= days_back <= 90, "days_back must be 1-90"
+ assert 1 <= timeout_seconds <= 120, "timeout_seconds must be 1-120"
+
+ if not config.BING_WEBMASTER_API_KEY or not config.BING_SITE_URL:
+ return 0 # Bing not configured — skip silently
+
+ started_at = datetime.utcnow()
+
+ try:
+ rows_synced = 0
+ async with httpx.AsyncClient(timeout=timeout_seconds) as client:
+ # Fetch query stats for the date range
+ response = await client.get(
+ "https://ssl.bing.com/webmaster/api.svc/json/GetQueryStats",
+ params={
+ "apikey": config.BING_WEBMASTER_API_KEY,
+ "siteUrl": config.BING_SITE_URL,
+ },
+ )
+ response.raise_for_status()
+ data = response.json()
+
+ # Bing returns {"d": [{"Query": ..., "Date": ..., ...}, ...]}
+ entries = data.get("d", []) if isinstance(data, dict) else data
+ if not isinstance(entries, list):
+ entries = []
+
+ cutoff = datetime.utcnow() - timedelta(days=days_back)
+
+ for entry in entries:
+ # Bing date format: "/Date(1708905600000)/" (ms since epoch)
+ date_str = entry.get("Date", "")
+ if "/Date(" in date_str:
+ ms = int(date_str.split("(")[1].split(")")[0])
+ entry_date = datetime.utcfromtimestamp(ms / 1000)
+ else:
+ continue
+
+ if entry_date < cutoff:
+ continue
+
+ metric_date = entry_date.strftime("%Y-%m-%d")
+ query = entry.get("Query", "")
+
+ await execute(
+ """INSERT OR REPLACE INTO seo_search_metrics
+ (source, metric_date, page_url, query, country, device,
+ clicks, impressions, ctr, position_avg)
+ VALUES ('bing', ?, '/', ?, NULL, NULL, ?, ?, ?, ?)""",
+ (
+ metric_date, query,
+ entry.get("Clicks", 0),
+ entry.get("Impressions", 0),
+ entry.get("AvgCTR", 0.0),
+ entry.get("AvgClickPosition", 0.0),
+ ),
+ )
+ rows_synced += 1
+
+ # Also fetch page-level stats
+ page_response = await client.get(
+ "https://ssl.bing.com/webmaster/api.svc/json/GetPageStats",
+ params={
+ "apikey": config.BING_WEBMASTER_API_KEY,
+ "siteUrl": config.BING_SITE_URL,
+ },
+ )
+ page_response.raise_for_status()
+ page_data = page_response.json()
+
+ page_entries = page_data.get("d", []) if isinstance(page_data, dict) else page_data
+ if not isinstance(page_entries, list):
+ page_entries = []
+
+ for entry in page_entries:
+ date_str = entry.get("Date", "")
+ if "/Date(" in date_str:
+ ms = int(date_str.split("(")[1].split(")")[0])
+ entry_date = datetime.utcfromtimestamp(ms / 1000)
+ else:
+ continue
+
+ if entry_date < cutoff:
+ continue
+
+ metric_date = entry_date.strftime("%Y-%m-%d")
+ page_url = _normalize_url(entry.get("Url", "/"))
+
+ await execute(
+ """INSERT OR REPLACE INTO seo_search_metrics
+ (source, metric_date, page_url, query, country, device,
+ clicks, impressions, ctr, position_avg)
+ VALUES ('bing', ?, ?, '', NULL, NULL, ?, ?, NULL, NULL)""",
+ (
+ metric_date, page_url,
+ entry.get("Clicks", 0),
+ entry.get("Impressions", 0),
+ ),
+ )
+ rows_synced += 1
+
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, started_at, completed_at, duration_ms)
+ VALUES ('bing', 'success', ?, ?, ?, ?)""",
+ (rows_synced, started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ return rows_synced
+
+ except Exception as exc:
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, error, started_at, completed_at, duration_ms)
+ VALUES ('bing', 'failed', 0, ?, ?, ?, ?)""",
+ (str(exc), started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ raise
diff --git a/web/src/padelnomics/seo/_gsc.py b/web/src/padelnomics/seo/_gsc.py
new file mode 100644
index 0000000..83fa70e
--- /dev/null
+++ b/web/src/padelnomics/seo/_gsc.py
@@ -0,0 +1,142 @@
+"""Google Search Console sync via Search Analytics API.
+
+Uses a service account JSON key file for auth. The google-api-python-client
+is synchronous, so sync runs in asyncio.to_thread().
+"""
+
+import asyncio
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.parse import urlparse
+
+from ..core import config, execute
+
+# GSC returns max 25K rows per request
+_ROWS_PER_PAGE = 25_000
+
+
+def _fetch_gsc_data(
+ start_date: str,
+ end_date: str,
+ max_pages: int,
+) -> list[dict]:
+ """Synchronous GSC fetch — called via asyncio.to_thread().
+
+ Returns list of dicts with keys: date, page, query, country, device,
+ clicks, impressions, ctr, position.
+ """
+ from google.oauth2.service_account import Credentials
+ from googleapiclient.discovery import build
+
+ key_path = Path(config.GSC_SERVICE_ACCOUNT_PATH)
+ assert key_path.exists(), f"GSC service account key not found: {key_path}"
+
+ credentials = Credentials.from_service_account_file(
+ str(key_path),
+ scopes=["https://www.googleapis.com/auth/webmasters.readonly"],
+ )
+ service = build("searchconsole", "v1", credentials=credentials)
+
+ all_rows = []
+ start_row = 0
+
+ for _page_num in range(max_pages):
+ body = {
+ "startDate": start_date,
+ "endDate": end_date,
+ "dimensions": ["date", "page", "query", "country", "device"],
+ "rowLimit": _ROWS_PER_PAGE,
+ "startRow": start_row,
+ }
+ response = service.searchanalytics().query(
+ siteUrl=config.GSC_SITE_URL,
+ body=body,
+ ).execute()
+
+ rows = response.get("rows", [])
+ if not rows:
+ break
+
+ for row in rows:
+ keys = row["keys"]
+ all_rows.append({
+ "date": keys[0],
+ "page": keys[1],
+ "query": keys[2],
+ "country": keys[3],
+ "device": keys[4],
+ "clicks": row.get("clicks", 0),
+ "impressions": row.get("impressions", 0),
+ "ctr": row.get("ctr", 0.0),
+ "position": row.get("position", 0.0),
+ })
+
+ if len(rows) < _ROWS_PER_PAGE:
+ break
+ start_row += _ROWS_PER_PAGE
+
+ return all_rows
+
+
+def _normalize_url(full_url: str) -> str:
+ """Strip a full URL to just the path (no domain).
+
+ Example: 'https://padelnomics.io/en/markets/germany/berlin' → '/en/markets/germany/berlin'
+ """
+ parsed = urlparse(full_url)
+ return parsed.path or "/"
+
+
+async def sync_gsc(days_back: int = 3, max_pages: int = 10) -> int:
+ """Sync GSC search analytics into seo_search_metrics. Returns rows synced."""
+ assert 1 <= days_back <= 90, "days_back must be 1-90"
+ assert 1 <= max_pages <= 20, "max_pages must be 1-20"
+
+ if not config.GSC_SERVICE_ACCOUNT_PATH or not config.GSC_SITE_URL:
+ return 0 # GSC not configured — skip silently
+
+ started_at = datetime.utcnow()
+
+ # GSC has ~2 day delay; fetch from days_back ago to 2 days ago
+ end_date = (datetime.utcnow() - timedelta(days=2)).strftime("%Y-%m-%d")
+ start_date = (datetime.utcnow() - timedelta(days=days_back + 2)).strftime("%Y-%m-%d")
+
+ try:
+ rows = await asyncio.to_thread(
+ _fetch_gsc_data, start_date, end_date, max_pages,
+ )
+
+ rows_synced = 0
+ for row in rows:
+ page_url = _normalize_url(row["page"])
+ await execute(
+ """INSERT OR REPLACE INTO seo_search_metrics
+ (source, metric_date, page_url, query, country, device,
+ clicks, impressions, ctr, position_avg)
+ VALUES ('gsc', ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+ (
+ row["date"], page_url, row["query"], row["country"],
+ row["device"], row["clicks"], row["impressions"],
+ row["ctr"], row["position"],
+ ),
+ )
+ rows_synced += 1
+
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, started_at, completed_at, duration_ms)
+ VALUES ('gsc', 'success', ?, ?, ?, ?)""",
+ (rows_synced, started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ return rows_synced
+
+ except Exception as exc:
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, error, started_at, completed_at, duration_ms)
+ VALUES ('gsc', 'failed', 0, ?, ?, ?, ?)""",
+ (str(exc), started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ raise
diff --git a/web/src/padelnomics/seo/_queries.py b/web/src/padelnomics/seo/_queries.py
new file mode 100644
index 0000000..94434c0
--- /dev/null
+++ b/web/src/padelnomics/seo/_queries.py
@@ -0,0 +1,379 @@
+"""SQL query functions for the admin SEO hub views.
+
+All heavy lifting happens in SQL. Functions accept filter parameters
+and return plain dicts/lists.
+"""
+
+from datetime import datetime, timedelta
+
+from ..core import execute, fetch_all, fetch_one
+
+
+def _date_cutoff(date_range_days: int) -> str:
+ """Return ISO date string for N days ago."""
+ return (datetime.utcnow() - timedelta(days=date_range_days)).strftime("%Y-%m-%d")
+
+
+async def get_search_performance(
+ date_range_days: int = 28,
+ source: str | None = None,
+) -> dict:
+ """Aggregate search performance: total clicks, impressions, avg CTR, avg position."""
+ assert 1 <= date_range_days <= 730
+
+ cutoff = _date_cutoff(date_range_days)
+ source_filter = "AND source = ?" if source else ""
+ params = [cutoff]
+ if source:
+ params.append(source)
+
+ row = await fetch_one(
+ f"""SELECT
+ COALESCE(SUM(clicks), 0) AS total_clicks,
+ COALESCE(SUM(impressions), 0) AS total_impressions,
+ CASE WHEN SUM(impressions) > 0
+ THEN CAST(SUM(clicks) AS REAL) / SUM(impressions)
+ ELSE 0 END AS avg_ctr,
+ CASE WHEN SUM(impressions) > 0
+ THEN SUM(position_avg * impressions) / SUM(impressions)
+ ELSE 0 END AS avg_position
+ FROM seo_search_metrics
+ WHERE metric_date >= ? {source_filter}""",
+ tuple(params),
+ )
+ return dict(row) if row else {
+ "total_clicks": 0, "total_impressions": 0,
+ "avg_ctr": 0, "avg_position": 0,
+ }
+
+
+async def get_top_queries(
+ date_range_days: int = 28,
+ source: str | None = None,
+ limit: int = 50,
+) -> list[dict]:
+ """Top queries by impressions with clicks, CTR, avg position."""
+ assert 1 <= date_range_days <= 730
+ assert 1 <= limit <= 500
+
+ cutoff = _date_cutoff(date_range_days)
+ source_filter = "AND source = ?" if source else ""
+ params: list = [cutoff]
+ if source:
+ params.append(source)
+ params.append(limit)
+
+ rows = await fetch_all(
+ f"""SELECT
+ query,
+ SUM(clicks) AS clicks,
+ SUM(impressions) AS impressions,
+ CASE WHEN SUM(impressions) > 0
+ THEN CAST(SUM(clicks) AS REAL) / SUM(impressions)
+ ELSE 0 END AS ctr,
+ CASE WHEN SUM(impressions) > 0
+ THEN SUM(position_avg * impressions) / SUM(impressions)
+ ELSE 0 END AS position_avg
+ FROM seo_search_metrics
+ WHERE metric_date >= ?
+ AND query IS NOT NULL AND query != ''
+ {source_filter}
+ GROUP BY query
+ ORDER BY impressions DESC
+ LIMIT ?""",
+ tuple(params),
+ )
+ return [dict(r) for r in rows]
+
+
+async def get_top_pages(
+ date_range_days: int = 28,
+ source: str | None = None,
+ limit: int = 50,
+) -> list[dict]:
+ """Top pages by impressions with clicks, CTR, avg position."""
+ assert 1 <= date_range_days <= 730
+ assert 1 <= limit <= 500
+
+ cutoff = _date_cutoff(date_range_days)
+ source_filter = "AND source = ?" if source else ""
+ params: list = [cutoff]
+ if source:
+ params.append(source)
+ params.append(limit)
+
+ rows = await fetch_all(
+ f"""SELECT
+ page_url,
+ SUM(clicks) AS clicks,
+ SUM(impressions) AS impressions,
+ CASE WHEN SUM(impressions) > 0
+ THEN CAST(SUM(clicks) AS REAL) / SUM(impressions)
+ ELSE 0 END AS ctr,
+ CASE WHEN SUM(impressions) > 0
+ THEN SUM(position_avg * impressions) / SUM(impressions)
+ ELSE 0 END AS position_avg
+ FROM seo_search_metrics
+ WHERE metric_date >= ?
+ {source_filter}
+ GROUP BY page_url
+ ORDER BY impressions DESC
+ LIMIT ?""",
+ tuple(params),
+ )
+ return [dict(r) for r in rows]
+
+
+async def get_country_breakdown(
+ date_range_days: int = 28,
+) -> list[dict]:
+ """Clicks and impressions by country."""
+ assert 1 <= date_range_days <= 730
+
+ cutoff = _date_cutoff(date_range_days)
+ rows = await fetch_all(
+ """SELECT
+ country,
+ SUM(clicks) AS clicks,
+ SUM(impressions) AS impressions
+ FROM seo_search_metrics
+ WHERE metric_date >= ?
+ AND country IS NOT NULL AND country != ''
+ GROUP BY country
+ ORDER BY impressions DESC
+ LIMIT 50""",
+ (cutoff,),
+ )
+ return [dict(r) for r in rows]
+
+
+async def get_device_breakdown(
+ date_range_days: int = 28,
+) -> list[dict]:
+ """Clicks and impressions by device type (GSC only)."""
+ assert 1 <= date_range_days <= 730
+
+ cutoff = _date_cutoff(date_range_days)
+ rows = await fetch_all(
+ """SELECT
+ device,
+ SUM(clicks) AS clicks,
+ SUM(impressions) AS impressions
+ FROM seo_search_metrics
+ WHERE metric_date >= ?
+ AND source = 'gsc'
+ AND device IS NOT NULL AND device != ''
+ GROUP BY device
+ ORDER BY impressions DESC""",
+ (cutoff,),
+ )
+ return [dict(r) for r in rows]
+
+
+async def get_funnel_metrics(
+ date_range_days: int = 28,
+) -> dict:
+ """Full funnel: search → analytics → conversions.
+
+ Combines search metrics (GSC/Bing), analytics (Umami), and
+ business metrics (planner users, leads) from SQLite.
+ """
+ assert 1 <= date_range_days <= 730
+
+ cutoff = _date_cutoff(date_range_days)
+
+ # Search layer
+ search = await fetch_one(
+ """SELECT
+ COALESCE(SUM(impressions), 0) AS impressions,
+ COALESCE(SUM(clicks), 0) AS clicks
+ FROM seo_search_metrics
+ WHERE metric_date >= ?""",
+ (cutoff,),
+ )
+
+ # Analytics layer
+ analytics = await fetch_one(
+ """SELECT
+ COALESCE(SUM(pageviews), 0) AS pageviews,
+ COALESCE(SUM(visitors), 0) AS visitors
+ FROM seo_analytics_metrics
+ WHERE metric_date >= ?
+ AND page_url != '/'""",
+ (cutoff,),
+ )
+
+ # Business layer (from existing SQLite tables)
+ planner_users = await fetch_one(
+ """SELECT COUNT(DISTINCT user_id) AS cnt
+ FROM scenarios
+ WHERE deleted_at IS NULL
+ AND created_at >= ?""",
+ (cutoff,),
+ )
+
+ leads = await fetch_one(
+ """SELECT COUNT(*) AS cnt
+ FROM lead_requests
+ WHERE lead_type = 'quote'
+ AND created_at >= ?""",
+ (cutoff,),
+ )
+
+ imp = search["impressions"] if search else 0
+ clicks = search["clicks"] if search else 0
+ pvs = analytics["pageviews"] if analytics else 0
+ vis = analytics["visitors"] if analytics else 0
+ planners = planner_users["cnt"] if planner_users else 0
+ lead_count = leads["cnt"] if leads else 0
+
+ return {
+ "impressions": imp,
+ "clicks": clicks,
+ "pageviews": pvs,
+ "visitors": vis,
+ "planner_users": planners,
+ "leads": lead_count,
+ # Conversion rates between stages
+ "ctr": clicks / imp if imp > 0 else 0,
+ "click_to_view": pvs / clicks if clicks > 0 else 0,
+ "view_to_visitor": vis / pvs if pvs > 0 else 0,
+ "visitor_to_planner": planners / vis if vis > 0 else 0,
+ "planner_to_lead": lead_count / planners if planners > 0 else 0,
+ }
+
+
+async def get_article_scorecard(
+ date_range_days: int = 28,
+ template_slug: str | None = None,
+ country: str | None = None,
+ language: str | None = None,
+ sort_by: str = "impressions",
+ sort_dir: str = "desc",
+ limit: int = 100,
+) -> list[dict]:
+ """Per-article scorecard joining articles + search + analytics metrics.
+
+ Returns article metadata enriched with search and analytics data,
+ plus attention flags for articles needing action.
+ """
+ assert 1 <= date_range_days <= 730
+ assert 1 <= limit <= 500
+ assert sort_dir in ("asc", "desc")
+
+ # Allowlist sort columns to prevent SQL injection
+ sort_columns = {
+ "impressions", "clicks", "ctr", "position_avg",
+ "pageviews", "title", "published_at",
+ }
+ if sort_by not in sort_columns:
+ sort_by = "impressions"
+
+ cutoff = _date_cutoff(date_range_days)
+
+ wheres = ["a.status = 'published'"]
+ params: list = [cutoff, cutoff]
+
+ if template_slug:
+ wheres.append("a.template_slug = ?")
+ params.append(template_slug)
+ if country:
+ wheres.append("a.country = ?")
+ params.append(country)
+ if language:
+ wheres.append("a.language = ?")
+ params.append(language)
+
+ where_clause = " AND ".join(wheres)
+ params.append(limit)
+
+ rows = await fetch_all(
+ f"""SELECT
+ a.id,
+ a.title,
+ a.url_path,
+ a.template_slug,
+ a.country,
+ a.language,
+ a.published_at,
+ COALESCE(s.impressions, 0) AS impressions,
+ COALESCE(s.clicks, 0) AS clicks,
+ COALESCE(s.ctr, 0) AS ctr,
+ COALESCE(s.position_avg, 0) AS position_avg,
+ COALESCE(u.pageviews, 0) AS pageviews,
+ COALESCE(u.visitors, 0) AS visitors,
+ u.bounce_rate,
+ u.time_avg_seconds,
+ -- Attention flags
+ CASE WHEN COALESCE(s.impressions, 0) > 100
+ AND COALESCE(s.ctr, 0) < 0.02
+ THEN 1 ELSE 0 END AS flag_low_ctr,
+ CASE WHEN COALESCE(s.clicks, 0) = 0
+ AND a.published_at <= date('now', '-30 days')
+ THEN 1 ELSE 0 END AS flag_no_clicks
+ FROM articles a
+ LEFT JOIN (
+ SELECT page_url,
+ SUM(impressions) AS impressions,
+ SUM(clicks) AS clicks,
+ CASE WHEN SUM(impressions) > 0
+ THEN CAST(SUM(clicks) AS REAL) / SUM(impressions)
+ ELSE 0 END AS ctr,
+ CASE WHEN SUM(impressions) > 0
+ THEN SUM(position_avg * impressions) / SUM(impressions)
+ ELSE 0 END AS position_avg
+ FROM seo_search_metrics
+ WHERE metric_date >= ?
+ GROUP BY page_url
+ ) s ON s.page_url = a.url_path
+ LEFT JOIN (
+ SELECT page_url,
+ SUM(pageviews) AS pageviews,
+ SUM(visitors) AS visitors,
+ AVG(bounce_rate) AS bounce_rate,
+ AVG(time_avg_seconds) AS time_avg_seconds
+ FROM seo_analytics_metrics
+ WHERE metric_date >= ?
+ GROUP BY page_url
+ ) u ON u.page_url = a.url_path
+ WHERE {where_clause}
+ ORDER BY {sort_by} {sort_dir}
+ LIMIT ?""",
+ tuple(params),
+ )
+ return [dict(r) for r in rows]
+
+
+async def get_sync_status() -> list[dict]:
+ """Last sync status for each source (gsc, bing, umami)."""
+ rows = await fetch_all(
+ """SELECT source, status, rows_synced, error,
+ started_at, completed_at, duration_ms
+ FROM seo_sync_log
+ WHERE id IN (
+ SELECT MAX(id) FROM seo_sync_log GROUP BY source
+ )
+ ORDER BY source"""
+ )
+ return [dict(r) for r in rows]
+
+
+async def cleanup_old_metrics(retention_days: int = 365) -> int:
+ """Delete metrics older than retention_days. Returns rows deleted."""
+ assert 30 <= retention_days <= 1095
+
+ cutoff = _date_cutoff(retention_days)
+
+ deleted_search = await execute(
+ "DELETE FROM seo_search_metrics WHERE metric_date < ?", (cutoff,)
+ )
+ deleted_analytics = await execute(
+ "DELETE FROM seo_analytics_metrics WHERE metric_date < ?", (cutoff,)
+ )
+ # Sync log: keep 30 days
+ sync_cutoff = _date_cutoff(30)
+ deleted_sync = await execute(
+ "DELETE FROM seo_sync_log WHERE started_at < ?", (sync_cutoff,)
+ )
+
+ return (deleted_search or 0) + (deleted_analytics or 0) + (deleted_sync or 0)
diff --git a/web/src/padelnomics/seo/_umami.py b/web/src/padelnomics/seo/_umami.py
new file mode 100644
index 0000000..c35f357
--- /dev/null
+++ b/web/src/padelnomics/seo/_umami.py
@@ -0,0 +1,116 @@
+"""Umami analytics sync via REST API.
+
+Uses bearer token auth. Self-hosted instance, no rate limits.
+Config already exists: UMAMI_API_URL, UMAMI_API_TOKEN, UMAMI_WEBSITE_ID.
+"""
+
+from datetime import datetime, timedelta
+
+import httpx
+
+from ..core import config, execute
+
+_TIMEOUT_SECONDS = 15
+
+
+async def sync_umami(days_back: int = 3, timeout_seconds: int = _TIMEOUT_SECONDS) -> int:
+ """Sync Umami per-URL metrics into seo_analytics_metrics. Returns rows synced."""
+ assert 1 <= days_back <= 90, "days_back must be 1-90"
+ assert 1 <= timeout_seconds <= 120, "timeout_seconds must be 1-120"
+
+ if not config.UMAMI_API_TOKEN or not config.UMAMI_API_URL:
+ return 0 # Umami not configured — skip silently
+
+ started_at = datetime.utcnow()
+
+ try:
+ rows_synced = 0
+ headers = {"Authorization": f"Bearer {config.UMAMI_API_TOKEN}"}
+ base = config.UMAMI_API_URL.rstrip("/")
+ website_id = config.UMAMI_WEBSITE_ID
+
+ async with httpx.AsyncClient(timeout=timeout_seconds, headers=headers) as client:
+ # Fetch per-URL metrics for each day individually
+ # (Umami's metrics endpoint returns totals for the period,
+ # so we query one day at a time for daily granularity)
+ for day_offset in range(days_back):
+ day = datetime.utcnow() - timedelta(days=day_offset + 1)
+ metric_date = day.strftime("%Y-%m-%d")
+ start_ms = int(day.replace(hour=0, minute=0, second=0).timestamp() * 1000)
+ end_ms = int(day.replace(hour=23, minute=59, second=59).timestamp() * 1000)
+
+ # Get URL-level metrics
+ response = await client.get(
+ f"{base}/api/websites/{website_id}/metrics",
+ params={
+ "startAt": start_ms,
+ "endAt": end_ms,
+ "type": "url",
+ "limit": 500,
+ },
+ )
+ response.raise_for_status()
+ url_metrics = response.json()
+
+ if not isinstance(url_metrics, list):
+ continue
+
+ for entry in url_metrics:
+ page_url = entry.get("x", "")
+ pageviews = entry.get("y", 0)
+
+ if not page_url:
+ continue
+
+ await execute(
+ """INSERT OR REPLACE INTO seo_analytics_metrics
+ (metric_date, page_url, pageviews, visitors,
+ bounce_rate, time_avg_seconds)
+ VALUES (?, ?, ?, 0, NULL, NULL)""",
+ (metric_date, page_url, pageviews),
+ )
+ rows_synced += 1
+
+ # Try to get overall stats for bounce rate and visit duration
+ # (Umami doesn't provide per-URL bounce rate, only site-wide)
+ stats_response = await client.get(
+ f"{base}/api/websites/{website_id}/stats",
+ params={"startAt": start_ms, "endAt": end_ms},
+ )
+ if stats_response.status_code == 200:
+ stats = stats_response.json()
+ visitors = stats.get("visitors", {}).get("value", 0)
+ bounce_rate = stats.get("bounces", {}).get("value", 0)
+ total_time = stats.get("totaltime", {}).get("value", 0)
+ page_count = stats.get("pageviews", {}).get("value", 1) or 1
+
+ # Store site-wide stats on the root URL for the day
+ avg_time = int(total_time / max(visitors, 1))
+ br = bounce_rate / max(visitors, 1) if visitors else 0
+
+ await execute(
+ """INSERT OR REPLACE INTO seo_analytics_metrics
+ (metric_date, page_url, pageviews, visitors,
+ bounce_rate, time_avg_seconds)
+ VALUES (?, '/', ?, ?, ?, ?)""",
+ (metric_date, page_count, visitors, br, avg_time),
+ )
+
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, started_at, completed_at, duration_ms)
+ VALUES ('umami', 'success', ?, ?, ?, ?)""",
+ (rows_synced, started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ return rows_synced
+
+ except Exception as exc:
+ duration_ms = int((datetime.utcnow() - started_at).total_seconds() * 1000)
+ await execute(
+ """INSERT INTO seo_sync_log
+ (source, status, rows_synced, error, started_at, completed_at, duration_ms)
+ VALUES ('umami', 'failed', 0, ?, ?, ?, ?)""",
+ (str(exc), started_at.isoformat(), datetime.utcnow().isoformat(), duration_ms),
+ )
+ raise
diff --git a/web/src/padelnomics/worker.py b/web/src/padelnomics/worker.py
index d639ee4..96b48d1 100644
--- a/web/src/padelnomics/worker.py
+++ b/web/src/padelnomics/worker.py
@@ -670,6 +670,45 @@ async def handle_cleanup_tasks(payload: dict) -> None:
)
+# =============================================================================
+# SEO Metrics Sync
+# =============================================================================
+
+@task("sync_gsc")
+async def handle_sync_gsc(payload: dict) -> None:
+ """Sync Google Search Console data."""
+ from .seo import sync_gsc
+ days_back = payload.get("days_back", 3)
+ rows = await sync_gsc(days_back=days_back)
+ print(f"[WORKER] GSC sync complete: {rows} rows")
+
+
+@task("sync_bing")
+async def handle_sync_bing(payload: dict) -> None:
+ """Sync Bing Webmaster data."""
+ from .seo import sync_bing
+ days_back = payload.get("days_back", 3)
+ rows = await sync_bing(days_back=days_back)
+ print(f"[WORKER] Bing sync complete: {rows} rows")
+
+
+@task("sync_umami")
+async def handle_sync_umami(payload: dict) -> None:
+ """Sync Umami analytics data."""
+ from .seo import sync_umami
+ days_back = payload.get("days_back", 3)
+ rows = await sync_umami(days_back=days_back)
+ print(f"[WORKER] Umami sync complete: {rows} rows")
+
+
+@task("cleanup_seo_metrics")
+async def handle_cleanup_seo_metrics(payload: dict) -> None:
+ """Delete SEO metrics older than 12 months."""
+ from .seo import cleanup_old_metrics
+ deleted = await cleanup_old_metrics(retention_days=365)
+ print(f"[WORKER] Cleaned up {deleted} old SEO metric rows")
+
+
# =============================================================================
# Worker Loop
# =============================================================================
@@ -723,6 +762,7 @@ async def run_scheduler() -> None:
await init_db()
last_credit_refill = None
+ last_seo_sync_date = None
while True:
try:
@@ -741,6 +781,17 @@ async def run_scheduler() -> None:
last_credit_refill = this_month
print(f"[SCHEDULER] Queued monthly credit refill for {this_month}")
+ # Daily SEO metrics sync — run once per day after 6am UTC
+ # (GSC data has ~2 day delay, syncing at 6am ensures data is ready)
+ today_date = today.strftime("%Y-%m-%d")
+ if last_seo_sync_date != today_date and today.hour >= 6:
+ await enqueue("sync_gsc")
+ await enqueue("sync_bing")
+ await enqueue("sync_umami")
+ await enqueue("cleanup_seo_metrics")
+ last_seo_sync_date = today_date
+ print(f"[SCHEDULER] Queued SEO metric syncs for {today_date}")
+
await asyncio.sleep(3600) # 1 hour
except Exception as e:
diff --git a/web/tests/test_seo.py b/web/tests/test_seo.py
new file mode 100644
index 0000000..708ee51
--- /dev/null
+++ b/web/tests/test_seo.py
@@ -0,0 +1,523 @@
+"""Tests for the SEO metrics module: queries, sync functions, admin routes."""
+
+from datetime import datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from padelnomics.seo._queries import (
+ cleanup_old_metrics,
+ get_article_scorecard,
+ get_country_breakdown,
+ get_device_breakdown,
+ get_funnel_metrics,
+ get_search_performance,
+ get_sync_status,
+ get_top_pages,
+ get_top_queries,
+)
+
+from padelnomics import core
+
+# ── Fixtures ──────────────────────────────────────────────────
+
+def _today():
+ return datetime.utcnow().strftime("%Y-%m-%d")
+
+
+def _days_ago(n: int) -> str:
+ return (datetime.utcnow() - timedelta(days=n)).strftime("%Y-%m-%d")
+
+
+@pytest.fixture
+async def seo_data(db):
+ """Populate seo_search_metrics and seo_analytics_metrics with sample data."""
+ today = _today()
+ yesterday = _days_ago(1)
+
+ # GSC search data
+ rows = [
+ ("gsc", today, "/en/markets/germany/berlin", "padel berlin", "de", "mobile", 50, 500, 0.10, 5.2),
+ ("gsc", today, "/en/markets/germany/munich", "padel munich", "de", "desktop", 30, 300, 0.10, 8.1),
+ ("gsc", today, "/en/markets/germany/berlin", "padel court cost", "de", "desktop", 10, 200, 0.05, 12.0),
+ ("gsc", yesterday, "/en/markets/germany/berlin", "padel berlin", "de", "mobile", 45, 480, 0.09, 5.5),
+ # Bing data
+ ("bing", today, "/", "padel business plan", None, None, 5, 100, 0.05, 15.0),
+ ]
+ for source, d, page, query, country, device, clicks, imp, ctr, pos in rows:
+ await db.execute(
+ """INSERT INTO seo_search_metrics
+ (source, metric_date, page_url, query, country, device,
+ clicks, impressions, ctr, position_avg)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+ (source, d, page, query, country, device, clicks, imp, ctr, pos),
+ )
+
+ # Umami analytics data
+ analytics_rows = [
+ (today, "/en/markets/germany/berlin", 120, 80, 0.35, 45),
+ (today, "/en/markets/germany/munich", 60, 40, 0.40, 30),
+ (today, "/", 200, 150, 0.50, 20),
+ ]
+ for d, page, pv, vis, br, t in analytics_rows:
+ await db.execute(
+ """INSERT INTO seo_analytics_metrics
+ (metric_date, page_url, pageviews, visitors, bounce_rate, time_avg_seconds)
+ VALUES (?, ?, ?, ?, ?, ?)""",
+ (d, page, pv, vis, br, t),
+ )
+
+ await db.commit()
+
+
+@pytest.fixture
+async def articles_data(db, seo_data):
+ """Create articles that match the SEO data URLs."""
+ now = datetime.utcnow().isoformat()
+ pub = _days_ago(10)
+
+ for title, url, tpl, lang in [
+ ("Padel in Berlin", "/en/markets/germany/berlin", "city-cost-de", "en"),
+ ("Padel in Munich", "/en/markets/germany/munich", "city-cost-de", "en"),
+ ]:
+ await db.execute(
+ """INSERT INTO articles
+ (url_path, slug, title, template_slug, language, status, published_at, created_at)
+ VALUES (?, ?, ?, ?, ?, 'published', ?, ?)""",
+ (url, url.split("/")[-1], title, tpl, lang, pub, now),
+ )
+ await db.commit()
+
+
+@pytest.fixture
+async def admin_client(app, db):
+ """Authenticated admin client."""
+ now = datetime.utcnow().isoformat()
+ async with db.execute(
+ "INSERT INTO users (email, name, created_at) VALUES (?, ?, ?)",
+ ("admin@test.com", "Admin", now),
+ ) as cursor:
+ admin_id = cursor.lastrowid
+ await db.execute(
+ "INSERT INTO user_roles (user_id, role) VALUES (?, 'admin')", (admin_id,)
+ )
+ await db.commit()
+
+ async with app.test_client() as c:
+ async with c.session_transaction() as sess:
+ sess["user_id"] = admin_id
+ yield c
+
+
+# ── Query function tests ─────────────────────────────────────
+
+class TestSearchPerformance:
+ """Tests for get_search_performance()."""
+
+ async def test_returns_aggregate_metrics(self, db, seo_data):
+ result = await get_search_performance(date_range_days=28)
+ assert result["total_clicks"] > 0
+ assert result["total_impressions"] > 0
+ assert 0 < result["avg_ctr"] < 1
+ assert result["avg_position"] > 0
+
+ async def test_filter_by_source(self, db, seo_data):
+ gsc = await get_search_performance(date_range_days=28, source="gsc")
+ bing = await get_search_performance(date_range_days=28, source="bing")
+ combined = await get_search_performance(date_range_days=28)
+ assert gsc["total_clicks"] + bing["total_clicks"] == combined["total_clicks"]
+
+ async def test_empty_data(self, db):
+ result = await get_search_performance(date_range_days=28)
+ assert result["total_clicks"] == 0
+ assert result["total_impressions"] == 0
+
+ async def test_date_range_filter(self, db, seo_data):
+ # Only today's data should match 1-day range
+ result = await get_search_performance(date_range_days=1)
+ # Yesterday's data excluded — fewer total clicks
+ full = await get_search_performance(date_range_days=28)
+ assert result["total_clicks"] <= full["total_clicks"]
+
+
+class TestTopQueries:
+ """Tests for get_top_queries()."""
+
+ async def test_returns_queries_sorted_by_impressions(self, db, seo_data):
+ queries = await get_top_queries(date_range_days=28)
+ assert len(queries) > 0
+ # Should be sorted desc by impressions
+ for i in range(len(queries) - 1):
+ assert queries[i]["impressions"] >= queries[i + 1]["impressions"]
+
+ async def test_limit(self, db, seo_data):
+ queries = await get_top_queries(date_range_days=28, limit=2)
+ assert len(queries) <= 2
+
+ async def test_filter_by_source(self, db, seo_data):
+ gsc_queries = await get_top_queries(source="gsc")
+ for q in gsc_queries:
+ assert q["query"] != "padel business plan" # that's bing data
+
+
+class TestTopPages:
+ """Tests for get_top_pages()."""
+
+ async def test_returns_pages(self, db, seo_data):
+ pages = await get_top_pages(date_range_days=28)
+ assert len(pages) > 0
+ # Berlin page should be first (most impressions)
+ assert pages[0]["page_url"] == "/en/markets/germany/berlin"
+
+
+class TestCountryBreakdown:
+ """Tests for get_country_breakdown()."""
+
+ async def test_returns_countries(self, db, seo_data):
+ countries = await get_country_breakdown(date_range_days=28)
+ assert len(countries) > 0
+ assert any(c["country"] == "de" for c in countries)
+
+
+class TestDeviceBreakdown:
+ """Tests for get_device_breakdown()."""
+
+ async def test_returns_devices_gsc_only(self, db, seo_data):
+ devices = await get_device_breakdown(date_range_days=28)
+ assert len(devices) > 0
+ device_names = [d["device"] for d in devices]
+ assert "mobile" in device_names
+ assert "desktop" in device_names
+
+
+class TestFunnelMetrics:
+ """Tests for get_funnel_metrics()."""
+
+ async def test_returns_all_stages(self, db, seo_data):
+ funnel = await get_funnel_metrics(date_range_days=28)
+ assert "impressions" in funnel
+ assert "clicks" in funnel
+ assert "pageviews" in funnel
+ assert "visitors" in funnel
+ assert "planner_users" in funnel
+ assert "leads" in funnel
+
+ async def test_conversion_rates(self, db, seo_data):
+ funnel = await get_funnel_metrics(date_range_days=28)
+ assert funnel["ctr"] > 0 # We have clicks and impressions
+ assert 0 <= funnel["ctr"] <= 1
+
+ async def test_empty_data(self, db):
+ funnel = await get_funnel_metrics(date_range_days=28)
+ assert funnel["impressions"] == 0
+ assert funnel["planner_users"] == 0
+
+
+class TestArticleScorecard:
+ """Tests for get_article_scorecard()."""
+
+ async def test_joins_articles_with_metrics(self, db, articles_data):
+ scorecard = await get_article_scorecard(date_range_days=28)
+ assert len(scorecard) == 2
+ berlin = next(a for a in scorecard if "berlin" in a["url_path"])
+ assert berlin["impressions"] > 0
+ assert berlin["pageviews"] > 0
+
+ async def test_filter_by_template(self, db, articles_data):
+ scorecard = await get_article_scorecard(
+ date_range_days=28, template_slug="city-cost-de",
+ )
+ assert len(scorecard) == 2
+ for a in scorecard:
+ assert a["template_slug"] == "city-cost-de"
+
+ async def test_sort_by_clicks(self, db, articles_data):
+ scorecard = await get_article_scorecard(
+ date_range_days=28, sort_by="clicks", sort_dir="desc",
+ )
+ if len(scorecard) >= 2:
+ assert scorecard[0]["clicks"] >= scorecard[1]["clicks"]
+
+ async def test_attention_flags(self, db, articles_data):
+ """Berlin has >100 impressions and low CTR — should flag."""
+ scorecard = await get_article_scorecard(date_range_days=28)
+ berlin = next(a for a in scorecard if "berlin" in a["url_path"])
+ # Berlin: 1180 impressions total, 105 clicks → CTR ~8.9% → no flag
+ # Flags depend on actual data; just check fields exist
+ assert "flag_low_ctr" in berlin
+ assert "flag_no_clicks" in berlin
+
+ async def test_invalid_sort_defaults_to_impressions(self, db, articles_data):
+ scorecard = await get_article_scorecard(
+ date_range_days=28, sort_by="invalid_column",
+ )
+ # Should not crash — falls back to impressions
+ assert len(scorecard) >= 0
+
+
+class TestSyncStatus:
+ """Tests for get_sync_status()."""
+
+ async def test_returns_last_sync_per_source(self, db):
+ now = datetime.utcnow().isoformat()
+ await db.execute(
+ """INSERT INTO seo_sync_log (source, status, rows_synced, started_at, completed_at, duration_ms)
+ VALUES ('gsc', 'success', 100, ?, ?, 500)""",
+ (now, now),
+ )
+ await db.execute(
+ """INSERT INTO seo_sync_log (source, status, rows_synced, started_at, completed_at, duration_ms)
+ VALUES ('umami', 'failed', 0, ?, ?, 200)""",
+ (now, now),
+ )
+ await db.commit()
+
+ status = await get_sync_status()
+ assert len(status) == 2
+ sources = {s["source"] for s in status}
+ assert "gsc" in sources
+ assert "umami" in sources
+
+ async def test_empty_when_no_syncs(self, db):
+ status = await get_sync_status()
+ assert status == []
+
+
+class TestCleanupOldMetrics:
+ """Tests for cleanup_old_metrics()."""
+
+ async def test_deletes_old_data(self, db):
+ old_date = (datetime.utcnow() - timedelta(days=400)).strftime("%Y-%m-%d")
+ recent_date = _today()
+
+ await db.execute(
+ """INSERT INTO seo_search_metrics
+ (source, metric_date, page_url, clicks, impressions)
+ VALUES ('gsc', ?, '/old', 1, 10)""",
+ (old_date,),
+ )
+ await db.execute(
+ """INSERT INTO seo_search_metrics
+ (source, metric_date, page_url, clicks, impressions)
+ VALUES ('gsc', ?, '/recent', 1, 10)""",
+ (recent_date,),
+ )
+ await db.commit()
+
+ deleted = await cleanup_old_metrics(retention_days=365)
+ assert deleted >= 1
+
+ rows = await core.fetch_all("SELECT * FROM seo_search_metrics")
+ assert len(rows) == 1
+ assert rows[0]["page_url"] == "/recent"
+
+
+# ── Sync function tests (mocked HTTP) ────────────────────────
+
+class TestSyncUmami:
+ """Tests for sync_umami() with mocked HTTP."""
+
+ async def test_skips_when_not_configured(self, db):
+ original = core.config.UMAMI_API_TOKEN
+ core.config.UMAMI_API_TOKEN = ""
+ try:
+ from padelnomics.seo._umami import sync_umami
+ result = await sync_umami(days_back=1)
+ assert result == 0
+ finally:
+ core.config.UMAMI_API_TOKEN = original
+
+ async def test_syncs_url_metrics(self, db):
+ from padelnomics.seo._umami import sync_umami
+
+ core.config.UMAMI_API_TOKEN = "test-token"
+ core.config.UMAMI_API_URL = "https://umami.test.io"
+
+ mock_metrics = [
+ {"x": "/en/markets/germany/berlin", "y": 50},
+ {"x": "/en/markets/germany/munich", "y": 30},
+ ]
+ mock_stats = {
+ "visitors": {"value": 100},
+ "bounces": {"value": 30},
+ "totaltime": {"value": 5000},
+ "pageviews": {"value": 200},
+ }
+
+ mock_response_metrics = MagicMock()
+ mock_response_metrics.status_code = 200
+ mock_response_metrics.json.return_value = mock_metrics
+ mock_response_metrics.raise_for_status = MagicMock()
+
+ mock_response_stats = MagicMock()
+ mock_response_stats.status_code = 200
+ mock_response_stats.json.return_value = mock_stats
+ mock_response_stats.raise_for_status = MagicMock()
+
+ async def mock_get(url, **kwargs):
+ if "/metrics" in url:
+ return mock_response_metrics
+ return mock_response_stats
+
+ mock_client = AsyncMock()
+ mock_client.get = mock_get
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=None)
+
+ with patch("padelnomics.seo._umami.httpx.AsyncClient", return_value=mock_client):
+ result = await sync_umami(days_back=1)
+
+ assert result == 2 # 2 URL metrics
+
+ # Verify data stored
+ rows = await core.fetch_all(
+ "SELECT * FROM seo_analytics_metrics WHERE page_url != '/'"
+ )
+ assert len(rows) == 2
+
+ # Verify sync log
+ log = await core.fetch_all("SELECT * FROM seo_sync_log WHERE source = 'umami'")
+ assert len(log) == 1
+ assert log[0]["status"] == "success"
+
+
+class TestSyncBing:
+ """Tests for sync_bing() with mocked HTTP."""
+
+ async def test_skips_when_not_configured(self, db):
+ original_key = core.config.BING_WEBMASTER_API_KEY
+ core.config.BING_WEBMASTER_API_KEY = ""
+ try:
+ from padelnomics.seo._bing import sync_bing
+ result = await sync_bing(days_back=1)
+ assert result == 0
+ finally:
+ core.config.BING_WEBMASTER_API_KEY = original_key
+
+
+class TestSyncGsc:
+ """Tests for sync_gsc() with mocked Google API."""
+
+ async def test_skips_when_not_configured(self, db):
+ original = core.config.GSC_SERVICE_ACCOUNT_PATH
+ core.config.GSC_SERVICE_ACCOUNT_PATH = ""
+ try:
+ from padelnomics.seo._gsc import sync_gsc
+ result = await sync_gsc(days_back=1)
+ assert result == 0
+ finally:
+ core.config.GSC_SERVICE_ACCOUNT_PATH = original
+
+
+# ── Admin route tests ─────────────────────────────────────────
+
+class TestSeoAdminRoutes:
+ """Tests for the SEO hub admin routes."""
+
+ async def test_seo_hub_loads(self, admin_client, db):
+ resp = await admin_client.get("/admin/seo")
+ assert resp.status_code == 200
+ text = await resp.get_data(as_text=True)
+ assert "SEO" in text
+
+ async def test_seo_hub_with_data(self, admin_client, db, seo_data):
+ resp = await admin_client.get("/admin/seo?days=28")
+ assert resp.status_code == 200
+
+ async def test_seo_search_partial(self, admin_client, db, seo_data):
+ resp = await admin_client.get("/admin/seo/search?days=28")
+ assert resp.status_code == 200
+ text = await resp.get_data(as_text=True)
+ assert "Top Queries" in text
+
+ async def test_seo_search_filter_by_source(self, admin_client, db, seo_data):
+ resp = await admin_client.get("/admin/seo/search?days=28&source=gsc")
+ assert resp.status_code == 200
+
+ async def test_seo_funnel_partial(self, admin_client, db, seo_data):
+ resp = await admin_client.get("/admin/seo/funnel?days=28")
+ assert resp.status_code == 200
+ text = await resp.get_data(as_text=True)
+ assert "Impressions" in text
+
+ async def test_seo_scorecard_partial(self, admin_client, db, articles_data):
+ resp = await admin_client.get("/admin/seo/scorecard?days=28")
+ assert resp.status_code == 200
+ text = await resp.get_data(as_text=True)
+ assert "Berlin" in text or "scorecard" in text.lower() or "articles" in text.lower()
+
+ async def test_seo_scorecard_filter(self, admin_client, db, articles_data):
+ resp = await admin_client.get(
+ "/admin/seo/scorecard?days=28&template_slug=city-cost-de&sort=clicks&dir=desc"
+ )
+ assert resp.status_code == 200
+
+ async def test_seo_sync_requires_auth(self, client, db):
+ resp = await client.post("/admin/seo/sync")
+ # Should redirect to login (302) or return 403
+ assert resp.status_code in (302, 403)
+
+ async def test_seo_sync_now(self, admin_client, db):
+ """Sync Now enqueues tasks."""
+ async with admin_client.session_transaction() as sess:
+ sess["csrf_token"] = "test"
+
+ resp = await admin_client.post(
+ "/admin/seo/sync",
+ form={"source": "all", "csrf_token": "test"},
+ )
+ # Should redirect back to SEO hub
+ assert resp.status_code == 302
+
+ # Verify tasks enqueued
+ tasks = await core.fetch_all(
+ "SELECT task_name FROM tasks WHERE task_name LIKE 'sync_%'"
+ )
+ task_names = {t["task_name"] for t in tasks}
+ assert "sync_gsc" in task_names
+ assert "sync_bing" in task_names
+ assert "sync_umami" in task_names
+
+ async def test_seo_sync_single_source(self, admin_client, db):
+ async with admin_client.session_transaction() as sess:
+ sess["csrf_token"] = "test"
+
+ resp = await admin_client.post(
+ "/admin/seo/sync",
+ form={"source": "gsc", "csrf_token": "test"},
+ )
+ assert resp.status_code == 302
+
+ tasks = await core.fetch_all("SELECT task_name FROM tasks WHERE task_name = 'sync_gsc'")
+ assert len(tasks) == 1
+
+ async def test_seo_hub_date_range(self, admin_client, db, seo_data):
+ for days in [7, 28, 90, 365]:
+ resp = await admin_client.get(f"/admin/seo?days={days}")
+ assert resp.status_code == 200
+
+ async def test_seo_sidebar_link(self, admin_client, db):
+ resp = await admin_client.get("/admin/")
+ text = await resp.get_data(as_text=True)
+ assert "SEO Hub" in text
+
+
+# ── Assertion boundary tests ─────────────────────────────────
+
+class TestQueryBounds:
+ """Test that query functions validate their bounds."""
+
+ async def test_search_performance_rejects_zero_days(self, db):
+ with pytest.raises(AssertionError):
+ await get_search_performance(date_range_days=0)
+
+ async def test_top_queries_rejects_zero_limit(self, db):
+ with pytest.raises(AssertionError):
+ await get_top_queries(limit=0)
+
+ async def test_cleanup_rejects_short_retention(self, db):
+ with pytest.raises(AssertionError):
+ await cleanup_old_metrics(retention_days=7)
+
+ async def test_scorecard_rejects_invalid_sort_dir(self, db):
+ with pytest.raises(AssertionError):
+ await get_article_scorecard(sort_dir="invalid")