Search Surface Monitoring Beyond Rank

# SERP features that appear above or alongside organic results
serp_features = {
    "ai_overview": "Google's AI-generated summary with source citations",
    "featured_snippet": "Paragraph, list, or table extracted from a page",
    "people_also_ask": "Expandable question boxes with extracted answers",
    "local_pack": "Map + 3 local business listings",
    "video_carousel": "Horizontal row of video results (YouTube-dominated)",
    "shopping_results": "Product cards with price, image, merchant",
    "knowledge_panel": "Right sidebar with entity information",
    "image_pack": "Row of image thumbnails inline in results",
    "top_stories": "News carousel for trending topics",
    "sitelinks": "Expanded links under a domain's main result",
}

# Which features matter for which intent
feature_by_intent = {
    "informational": ["ai_overview", "featured_snippet", "people_also_ask"],
    "navigational":  ["knowledge_panel", "sitelinks"],
    "commercial":    ["shopping_results", "local_pack"],
    "video":         ["video_carousel"],
}

import requests, os, json

def capture_full_serp(query: str) -> dict:
    """Capture all SERP features, not just organic positions."""
    resp = requests.post(
        "https://api.scavio.dev/api/v1/search",
        headers={"x-api-key": os.environ["SCAVIO_API_KEY"]},
        json={"query": query, "platform": "google", "country_code": "us"},
        timeout=15,
    )
    data = resp.json()

    surface = {
        "query": query,
        "organic_count": len(data.get("organic_results", [])),
        "ai_overview": bool(data.get("ai_overview")),
        "ai_overview_sources": [],
        "featured_snippet": None,
        "paa_questions": [],
        "local_pack": [],
        "video_results": [],
    }

    # Extract AI Overview citations
    ao = data.get("ai_overview", {})
    if ao:
        for source in ao.get("sources", []):
            surface["ai_overview_sources"].append(source.get("link", ""))

    # Featured snippet
    fs = data.get("featured_snippet")
    if fs:
        surface["featured_snippet"] = {
            "domain": fs.get("displayed_link", ""),
            "type": fs.get("type", "paragraph"),
        }

    # People Also Ask
    for paa in data.get("people_also_ask", []):
        surface["paa_questions"].append(paa.get("question", ""))

    # Local pack
    for local in data.get("local_pack", []):
        surface["local_pack"].append(local.get("title", ""))

    return surface

# 1 credit per query -- captures entire surface
result = capture_full_serp("best coffee shop downtown austin")
print(json.dumps(result, indent=2))

def detect_surface_changes(previous: dict, current: dict) -> list:
    """Compare two SERP captures and flag meaningful changes."""
    changes = []

    # AI Overview appeared or disappeared
    if previous["ai_overview"] != current["ai_overview"]:
        status = "appeared" if current["ai_overview"] else "disappeared"
        changes.append(f"AI Overview {status}")

    # Your domain entered/exited AI Overview citations
    my_domain = "yoursite.com"
    was_cited = any(my_domain in s for s in previous.get("ai_overview_sources", []))
    now_cited = any(my_domain in s for s in current.get("ai_overview_sources", []))
    if was_cited and not now_cited:
        changes.append("Lost AI Overview citation")
    elif not was_cited and now_cited:
        changes.append("Gained AI Overview citation")

    # Featured snippet ownership changed
    prev_fs = (previous.get("featured_snippet") or {}).get("domain", "")
    curr_fs = (current.get("featured_snippet") or {}).get("domain", "")
    if prev_fs != curr_fs:
        changes.append(f"Featured snippet: {prev_fs} -> {curr_fs}")

    # New PAA questions appeared
    new_paa = set(current["paa_questions"]) - set(previous["paa_questions"])
    if new_paa:
        changes.append(f"New PAA questions: {len(new_paa)}")

    return changes