How to Run a GEO/AEO Audit with a Search API

import os, requests, json
from datetime import datetime

API_KEY = os.environ['SCAVIO_API_KEY']
SH = {'x-api-key': API_KEY, 'Content-Type': 'application/json'}

BRAND = 'scavio'
BRAND_TERMS = ['scavio', 'scavio.dev', 'scavio api']
AUDIT_KEYWORDS = [
    'best serp api', 'search api for developers', 'google search api python',
    'web scraping api alternative', 'ai agent search tool', 'mcp search server',
    'serp api pricing', 'multi platform search api', 'reddit data api',
    'tiktok analytics api', 'amazon product search api', 'youtube search api',
    'search api comparison 2026', 'best api for ai agents', 'serp data provider',
    'google results api', 'search api latency', 'web data api for startups',
    'search api free tier', 'search api mcp integration'
]
print(f'GEO/AEO Audit for "{BRAND}" across {len(AUDIT_KEYWORDS)} keywords')
print(f'Estimated cost: ${len(AUDIT_KEYWORDS) * 0.005:.2f}')

def audit_keyword(keyword, brand_terms):
    data = requests.post('https://api.scavio.dev/api/v1/search',
        headers=SH, json={'query': keyword, 'country_code': 'us',
                          'include_ai_overview': True}).json()
    ao = data.get('ai_overview', {})
    ao_text = json.dumps(ao).lower() if ao else ''
    cited = any(b.lower() in ao_text for b in brand_terms)
    organic = data.get('organic_results', [])
    position = next((r['position'] for r in organic
        if any(b in r.get('link', '').lower() for b in brand_terms)), None)
    has_fs = bool(data.get('answer_box'))
    paa = len(data.get('related_questions', []))
    return {
        'keyword': keyword, 'has_ao': bool(ao), 'brand_cited': cited,
        'organic_position': position, 'has_featured_snippet': has_fs,
        'paa_count': paa
    }

results = []
for kw in AUDIT_KEYWORDS:
    r = audit_keyword(kw, BRAND_TERMS)
    results.append(r)
    status = 'CITED' if r['brand_cited'] else 'AO' if r['has_ao'] else '---'
    pos = f'#{r["organic_position"]}' if r['organic_position'] else '-'
    print(f'  [{status:6}] {kw:35} | Organic: {pos:4} | PAA: {r["paa_count"]}')

def calculate_geo_score(results):
    total = len(results)
    ao_present = sum(1 for r in results if r['has_ao'])
    brand_cited = sum(1 for r in results if r['brand_cited'])
    top_10 = sum(1 for r in results if r['organic_position'] and r['organic_position'] <= 10)
    top_3 = sum(1 for r in results if r['organic_position'] and r['organic_position'] <= 3)
    # Weighted score (0-100)
    score = (
        (brand_cited / total * 40) +  # 40% weight: AO citations
        (top_3 / total * 25) +         # 25% weight: top 3 rankings
        (top_10 / total * 20) +        # 20% weight: top 10 rankings
        (ao_present / total * 15)      # 15% weight: AO keyword coverage
    ) * 100 / 100
    return {
        'score': round(score, 1),
        'ao_presence_rate': round(ao_present / total * 100, 1),
        'citation_rate': round(brand_cited / total * 100, 1),
        'top_3_rate': round(top_3 / total * 100, 1),
        'top_10_rate': round(top_10 / total * 100, 1),
        'total_keywords': total
    }

scores = calculate_geo_score(results)
print(f'\nGEO Visibility Score: {scores["score"]}/100')
for k, v in scores.items():
    if k != 'score':
        print(f'  {k}: {v}')

def geo_audit_report(results, scores):
    print(f'\n{"=" * 60}')
    print(f'GEO/AEO Audit Report - {datetime.now().strftime("%Y-%m-%d")}')
    print(f'Brand: {BRAND} | Keywords: {scores["total_keywords"]}')
    print(f'{"=" * 60}')
    print(f'\nOverall Score: {scores["score"]}/100')
    if scores['score'] >= 70: grade = 'STRONG'
    elif scores['score'] >= 40: grade = 'MODERATE'
    else: grade = 'NEEDS WORK'
    print(f'Grade: {grade}')
    print(f'\nMetrics:')
    print(f'  AI Overview presence: {scores["ao_presence_rate"]}%')
    print(f'  Brand cited in AO: {scores["citation_rate"]}%')
    print(f'  Top 3 organic: {scores["top_3_rate"]}%')
    print(f'  Top 10 organic: {scores["top_10_rate"]}%')
    # Opportunities
    uncited_ao = [r for r in results if r['has_ao'] and not r['brand_cited']]
    print(f'\nOpportunities ({len(uncited_ao)} keywords with AO but no brand citation):')
    for r in uncited_ao[:5]:
        print(f'  - {r["keyword"]} (organic #{r["organic_position"] or "not ranked"})')
    print(f'\nAudit cost: ${len(results) * 0.005:.2f}')

geo_audit_report(results, scores)