How to Track AI Overview Citations for Your Brand

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'}

DOMAIN = 'yourbrand.com'
COMPETITORS = ['competitor1.com', 'competitor2.com']
KEYWORDS = [
    'best project management tool',
    'project management software comparison',
    'agile vs waterfall tools',
    'remote team project management',
    'project management for startups',
]

def scan_citations(keyword):
    data = requests.post('https://api.scavio.dev/api/v1/search',
        headers=SH, json={'query': keyword, 'country_code': 'us'}).json()
    aio = data.get('ai_overview', data.get('answer_box', {}))
    aio_text = json.dumps(aio).lower() if aio else ''
    result = {
        'keyword': keyword,
        'has_aio': bool(aio),
        'brand_cited': DOMAIN.lower() in aio_text,
        'competitors_cited': {c: c.lower() in aio_text for c in COMPETITORS}
    }
    return result

results = []
for kw in KEYWORDS:
    r = scan_citations(kw)
    results.append(r)
    brand = 'CITED' if r['brand_cited'] else 'absent'
    comps = sum(1 for v in r['competitors_cited'].values() if v)
    print(f'  [{brand:6}] {kw:45} | competitors: {comps}/{len(COMPETITORS)}')
print(f'\nCost: ${len(KEYWORDS) * 0.005:.3f}')

def citation_report(results):
    total = len(results)
    with_aio = sum(1 for r in results if r['has_aio'])
    brand_cited = sum(1 for r in results if r['brand_cited'])
    print(f'\n=== AI Citation Report - {DOMAIN} ===')
    print(f'  Keywords: {total}')
    print(f'  AI Overviews present: {with_aio} ({with_aio/total*100:.0f}%)')
    print(f'  Your brand cited: {brand_cited} ({brand_cited/with_aio*100:.0f}% of AIO)' if with_aio else '  No AI Overviews found')
    # Competitor comparison
    print(f'\n  Citation Share:')
    comp_counts = {c: sum(1 for r in results if r['competitors_cited'].get(c)) for c in COMPETITORS}
    all_brands = {DOMAIN: brand_cited, **comp_counts}
    for brand, count in sorted(all_brands.items(), key=lambda x: x[1], reverse=True):
        bar = '#' * count
        print(f'    {brand:25} | {count:2} citations | {bar}')
    # Gaps: keywords where competitors are cited but you are not
    gaps = [r for r in results if r['has_aio'] and not r['brand_cited'] and any(r['competitors_cited'].values())]
    if gaps:
        print(f'\n  Citation Gaps ({len(gaps)} keywords where competitors beat you):')
        for g in gaps:
            cited_comps = [c for c, v in g['competitors_cited'].items() if v]
            print(f'    "{g["keyword"]}" -> cited: {", ".join(cited_comps)}')

citation_report(results)

def track_changes(results, history_file='citation_history.json'):
    try:
        with open(history_file) as f:
            history = json.load(f)
    except FileNotFoundError:
        history = []
    today = {
        'date': datetime.now().strftime('%Y-%m-%d'),
        'total': len(results),
        'aio_count': sum(1 for r in results if r['has_aio']),
        'cited': sum(1 for r in results if r['brand_cited']),
        'keywords': {r['keyword']: r['brand_cited'] for r in results}
    }
    changes = []
    if history:
        prev = history[-1]
        prev_kws = prev.get('keywords', {})
        for kw, cited in today['keywords'].items():
            if kw in prev_kws and prev_kws[kw] != cited:
                change = 'GAINED' if cited else 'LOST'
                changes.append(f'{change}: "{kw}"')
    history.append(today)
    with open(history_file, 'w') as f:
        json.dump(history, f, indent=2)
    print(f'\n=== Citation Changes ===')
    if changes:
        for c in changes:
            print(f'  {c}')
    else:
        print(f'  No changes since last scan.')
    print(f'  History: {len(history)} scans saved')

track_changes(results)