TikTok Creator Discovery for Agencies via API

import requests, os

API_KEY = os.environ["SCAVIO_API_KEY"]
BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {API_KEY}",
           "Content-Type": "application/json"}

def discover_creators(keywords, min_followers=5000, max_followers=500000):
    candidates = []
    seen = set()
    for kw in keywords:
        cursor = "0"
        for _ in range(3):
            resp = requests.post(f"{BASE}/api/v1/tiktok/search/users",
                headers=HEADERS,
                json={"keyword": kw, "cursor": cursor, "count": 30})
            data = resp.json()["data"]
            for u in data.get("user_list", []):
                info = u["user_info"]
                uid = info["unique_id"]
                if uid in seen:
                    continue
                seen.add(uid)
                fc = info.get("follower_count", 0)
                if min_followers <= fc <= max_followers:
                    candidates.append({
                        "username": uid,
                        "nickname": info.get("nickname", ""),
                        "followers": fc,
                        "sec_uid": info["sec_uid"],
                        "bio": info.get("signature", ""),
                        "source_keyword": kw,
                    })
            if not data.get("has_more"):
                break
            cursor = str(data.get("cursor", "0"))
    return sorted(candidates, key=lambda x: x["followers"], reverse=True)

creators = discover_creators(
    ["fitness coach", "home workout", "gym motivation"],
    min_followers=10000, max_followers=200000)
print(f"Found {len(creators)} creators in range")
for c in creators[:10]:
    print(f"  @{c['username']} | {c['followers']:,} | {c['source_keyword']}")

def enrich_creator(creator):
    resp = requests.post(f"{BASE}/api/v1/tiktok/user/posts",
        headers=HEADERS,
        json={"sec_user_id": creator["sec_uid"],
              "count": 15, "sort_type": "0"})
    posts = resp.json()["data"].get("aweme_list", [])
    if not posts:
        return {**creator, "avg_views": 0, "engagement_rate": 0,
                "posts_per_week": 0}

    views = [p["statistics"]["play_count"] for p in posts]
    engagements = [p["statistics"]["digg_count"] +
                   p["statistics"]["comment_count"] +
                   p["statistics"]["share_count"] for p in posts]
    avg_eng = sum(engagements) / len(engagements)
    er = avg_eng / creator["followers"] * 100 if creator["followers"] > 0 else 0

    timestamps = sorted(p["create_time"] for p in posts)
    days = (timestamps[-1] - timestamps[0]) / 86400 if len(timestamps) > 1 else 7
    ppw = len(posts) / (days / 7) if days > 0 else 0

    return {**creator,
            "avg_views": int(sum(views) / len(views)),
            "engagement_rate": round(er, 2),
            "posts_per_week": round(ppw, 1)}

# Enrich top candidates (2 credits each: profile already fetched + posts)
enriched = [enrich_creator(c) for c in creators[:20]]
# Filter for good engagement
qualified = [c for c in enriched if c["engagement_rate"] > 3.0
             and c["posts_per_week"] >= 2]
print(f"{len(qualified)} creators with >3% ER and 2+ posts/week")

import csv

def export_shortlist(creators, filename="creator_shortlist.csv"):
    with open(filename, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=[
            "username", "followers", "avg_views",
            "engagement_rate", "posts_per_week", "bio"])
        writer.writeheader()
        for c in creators:
            writer.writerow({
                "username": f"@{c['username']}",
                "followers": c["followers"],
                "avg_views": c.get("avg_views", ""),
                "engagement_rate": f"{c.get('engagement_rate', 0)}%",
                "posts_per_week": c.get("posts_per_week", ""),
                "bio": c.get("bio", "")[:100],
            })
    print(f"Exported {len(creators)} creators to {filename}")

export_shortlist(qualified)