How to Build an Agency Rank Tracker with a Search API

CLIENTS = [
    {
        'name': 'Client A',
        'domain': 'clienta.com',
        'keywords': ['crm software', 'best crm 2026', 'crm for startups', 'crm comparison'],
    },
    {
        'name': 'Client B',
        'domain': 'clientb.io',
        'keywords': ['project management tool', 'team collaboration app', 'agile project management'],
    },
]

import requests, os

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

def check_rank(keyword: str, target_domain: str) -> dict:
    resp = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
        json={'platform': 'google', 'query': keyword}, timeout=10)
    results = resp.json().get('organic', [])
    
    for i, r in enumerate(results):
        url = r.get('link', '')
        if target_domain in url:
            return {'keyword': keyword, 'position': i + 1, 'url': url, 'title': r.get('title','')}
    
    return {'keyword': keyword, 'position': None, 'not_in_top_results': True}

import json
from datetime import date
from pathlib import Path

def daily_client_check(client: dict) -> dict:
    today = date.today().isoformat()
    results = []
    for kw in client['keywords']:
        rank = check_rank(kw, client['domain'])
        rank['date'] = today
        results.append(rank)
    
    # Store history
    history_file = Path(f"ranks_{client['name'].replace(' ','_').lower()}.json")
    history = json.loads(history_file.read_text()) if history_file.exists() else []
    history.extend(results)
    history_file.write_text(json.dumps(history, indent=2))
    
    return {
        'client': client['name'],
        'date': today,
        'tracked': len(results),
        'ranking': sum(1 for r in results if r.get('position')),
        'avg_position': sum(r['position'] for r in results if r.get('position')) / max(sum(1 for r in results if r.get('position')), 1),
        'results': results,
    }

def client_report(client_name: str, days: int = 7) -> dict:
    history_file = Path(f"ranks_{client_name.replace(' ','_').lower()}.json")
    if not history_file.exists():
        return {'error': 'No data found'}
    
    history = json.loads(history_file.read_text())
    dates = sorted(set(r['date'] for r in history))[-days:]
    
    report = {'client': client_name, 'period': f'Last {days} days', 'keywords': {}}
    for kw in set(r['keyword'] for r in history):
        kw_data = [r for r in history if r['keyword'] == kw and r['date'] in dates]
        if len(kw_data) >= 2:
            first = next((r['position'] for r in kw_data if r.get('position')), None)
            last = next((r['position'] for r in reversed(kw_data) if r.get('position')), None)
            if first and last:
                report['keywords'][kw] = {'current': last, 'change': first - last, 'trend': 'up' if last < first else 'down' if last > first else 'stable'}
    
    return report