TikTok Creator Network Mapping via API

import requests, os, json, time

API_BASE = "https://api.scavio.dev/api/v1/tiktok"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}"}

def get_profile(username: str) -> dict:
    """Fetch a TikTok creator's profile."""
    resp = requests.post(
        f"{API_BASE}/profile",
        headers=HEADERS,
        json={"username": username},
        timeout=15,
    )
    data = resp.json()
    return {
        "username": username,
        "followers": data.get("follower_count", 0),
        "following": data.get("following_count", 0),
        "likes": data.get("heart_count", 0),
        "videos": data.get("video_count", 0),
        "bio": data.get("signature", ""),
    }

# Seed creators: start with known creators in your niche
seed_creators = ["creator_a", "creator_b", "creator_c"]
profiles = {name: get_profile(name) for name in seed_creators}

# 1 credit per profile lookup
# 3 seed creators = 3 credits = $0.015

def get_followings(username: str, max_pages: int = 3) -> list:
    """Get list of accounts a creator follows."""
    followings = []
    cursor = None

    for _ in range(max_pages):
        payload = {"username": username}
        if cursor:
            payload["cursor"] = cursor

        resp = requests.post(
            f"{API_BASE}/user/followings",
            headers=HEADERS,
            json=payload,
            timeout=15,
        )
        data = resp.json()
        users = data.get("users", [])
        followings.extend([u.get("unique_id", "") for u in users])

        cursor = data.get("cursor")
        if not cursor or not users:
            break
        time.sleep(0.5)

    return followings

def get_followers(username: str, max_pages: int = 3) -> list:
    """Get list of accounts that follow a creator."""
    followers = []
    cursor = None

    for _ in range(max_pages):
        payload = {"username": username}
        if cursor:
            payload["cursor"] = cursor

        resp = requests.post(
            f"{API_BASE}/user/followers",
            headers=HEADERS,
            json=payload,
            timeout=15,
        )
        data = resp.json()
        users = data.get("users", [])
        followers.extend([u.get("unique_id", "") for u in users])

        cursor = data.get("cursor")
        if not cursor or not users:
            break
        time.sleep(0.5)

    return followers

# Map connections for each seed creator
# ~3 credits per creator (3 pages) for followings
# ~3 credits per creator for followers
connections = {}
for name in seed_creators:
    connections[name] = {
        "followings": get_followings(name),
        "followers": get_followers(name),
    }

from collections import Counter

def find_mutual_connections(connections: dict) -> dict:
    """Find creators who follow each other (mutual connections)."""
    mutuals = {}

    for creator, data in connections.items():
        followings_set = set(data["followings"])
        followers_set = set(data["followers"])
        mutuals[creator] = list(followings_set.intersection(followers_set))

    return mutuals

def find_cluster_candidates(connections: dict, min_overlap: int = 2) -> list:
    """Find accounts that multiple seed creators follow."""
    all_followings = []
    for data in connections.values():
        all_followings.extend(data["followings"])

    # Count how many seed creators follow each account
    overlap = Counter(all_followings)
    clusters = [
        {"username": user, "followed_by_count": count}
        for user, count in overlap.most_common()
        if count >= min_overlap
    ]

    return clusters

# Find creators followed by 2+ seed creators
cluster_candidates = find_cluster_candidates(connections, min_overlap=2)
print(f"Found {len(cluster_candidates)} cluster candidates")

for c in cluster_candidates[:10]:
    print(f"  {c['username']}: followed by {c['followed_by_count']} seed creators")

def score_creator_for_campaign(username: str) -> dict:
    """Score a creator's potential for campaign collaboration."""
    profile = get_profile(username)

    # Engagement rate estimate (likes / followers / videos)
    if profile["followers"] > 0 and profile["videos"] > 0:
        avg_likes_per_video = profile["likes"] / max(profile["videos"], 1)
        engagement_rate = avg_likes_per_video / profile["followers"]
    else:
        engagement_rate = 0

    # Micro-influencer sweet spot: 10k-100k followers
    follower_score = 0
    if 10000 <= profile["followers"] <= 100000:
        follower_score = 3  # Micro-influencer (highest value per dollar)
    elif 1000 <= profile["followers"] < 10000:
        follower_score = 2  # Nano-influencer
    elif 100000 < profile["followers"] <= 500000:
        follower_score = 1  # Mid-tier
    else:
        follower_score = 0  # Too small or too large

    return {
        "username": username,
        "followers": profile["followers"],
        "engagement_rate": round(engagement_rate, 4),
        "follower_score": follower_score,
        "total_score": follower_score + (1 if engagement_rate > 0.03 else 0),
        "bio": profile["bio"][:100],
    }

# Score top cluster candidates (1 credit each for profile lookup)
scored = [score_creator_for_campaign(c["username"]) for c in cluster_candidates[:20]]
scored.sort(key=lambda x: x["total_score"], reverse=True)

for s in scored[:10]:
    print(f"{s['username']}: score={s['total_score']}, "
          f"followers={s['followers']:,}, "
          f"engagement={s['engagement_rate']:.2%}")