AI Overview Tracking for Small Agencies on a Budget

import os, requests, json
from datetime import datetime

SCAVIO_KEY = os.environ["SCAVIO_API_KEY"]
HEADERS = {"x-api-key": SCAVIO_KEY}

def track_ai_overviews(client: dict) -> list:
    """Track AI Overview status for a client's keywords."""
    results = []
    for kw in client["keywords"]:
        resp = requests.post(
            "https://api.scavio.dev/api/v1/search",
            headers=HEADERS,
            json={
                "query": kw,
                "num_results": 10,
                "include_ai_overview": True,
            },
        )
        data = resp.json()
        ai_overview = data.get("ai_overview", {})
        organic = data.get("organic_results", [])

        # Check if client domain appears in AI Overview citations
        client_cited = False
        if ai_overview:
            citations = ai_overview.get("citations", [])
            client_cited = any(
                client["domain"] in str(c) for c in citations
            )

        # Check organic ranking
        client_rank = None
        for i, r in enumerate(organic):
            if client["domain"] in r.get("link", ""):
                client_rank = i + 1
                break

        results.append({
            "keyword": kw,
            "has_ai_overview": bool(ai_overview),
            "client_cited_in_aio": client_cited,
            "organic_rank": client_rank,
            "date": datetime.utcnow().strftime("%Y-%m-%d"),
        })
    return results

# Example: 50 keywords per client = 50 credits = $0.25
client = {
    "name": "Austin Dental Group",
    "domain": "austindental.com",
    "keywords": [
        "best dentist austin",
        "teeth whitening austin tx",
        "dental implants cost austin",
        "emergency dentist austin",
    ],
}
report = track_ai_overviews(client)

def generate_monthly_report(client_name: str, data: list) -> str:
    """Generate a plain-text monthly AEO report."""
    total = len(data)
    with_aio = sum(1 for d in data if d["has_ai_overview"])
    cited = sum(1 for d in data if d["client_cited_in_aio"])
    ranked = sum(1 for d in data if d["organic_rank"] and d["organic_rank"] <= 10)

    report = f"""AEO Report: {client_name}
Period: {data[0]['date'] if data else 'N/A'}
Keywords tracked: {total}
Keywords with AI Overview: {with_aio} ({with_aio*100//max(total,1)}%)
Client cited in AI Overview: {cited} ({cited*100//max(with_aio,1)}% of AIO keywords)
Organic top-10 rankings: {ranked} ({ranked*100//max(total,1)}%)

Keywords where you appear in AI Overview:
"""
    for d in data:
        if d["client_cited_in_aio"]:
            report += f"  - {d['keyword']} (organic rank: {d['organic_rank'] or 'not ranked'})
"

    report += "
Keywords with AI Overview but no citation:
"
    for d in data:
        if d["has_ai_overview"] and not d["client_cited_in_aio"]:
            report += f"  - {d['keyword']} (organic rank: {d['organic_rank'] or 'not ranked'})
"

    return report

print(generate_monthly_report(client["name"], report))