TikTok Ad Library API: get a brand's ads and videos

export TOOLZERHUB_API_KEY=your_key
END=$(date +%s); START=$((END - 30 * 86400))
curl -H "x-api-key: $TOOLZERHUB_API_KEY" \
  "https://api.toolzerhub.com/v1/tiktok-ads/search?region=GB&query=nike&start_time=$START&end_time=$END"

{
  "id": "1877122884181393",
  "name": "lianalastique",
  "title": "@Nike   #nike #sports ",
  "first_shown_date": 1790121600000,
  "last_shown_date": 1790121600000,
  "estimated_audience": "0-1K",
  "subject": "Apparel & Accessories",
  "videos": [{ "video_url": "https://library.tiktok.com/api/v1/cdn/1792604592/video/..." }]
}

import csv
import os
import sys
import time
from datetime import datetime, timezone

import requests

BASE = "https://api.toolzerhub.com/v1/tiktok-ads"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["ad_id", "advertiser", "title", "first_shown", "last_shown", "reach", "video_file"]
VIDEO_HEADERS = {"User-Agent": "Mozilla/5.0"}  # the video host 403s requests' default one


def get(path, params, tries=3):
    # 429, 500 and 503 are retried with a growing pause; failed calls cost no credits.
    for attempt in range(tries):
        r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=90)
        if r.status_code in (429, 500, 503) and attempt < tries - 1:
            time.sleep(10 * (attempt + 1))
            continue
        r.raise_for_status()
        return r.json()["data"]


def advertiser_id(name):
    found = get("suggestions", {"query": name})["data"]["adv_names"]
    for adv in found:
        if adv["name"].lower() == name.lower():
            return adv["ids"]
    sys.exit("No exact match. TikTok suggests: " + "; ".join(a["name"] for a in found))


def ads(name, region, days, pages):
    end = int(time.time())
    params = {"region": region, "query": name, "search_type": "advertiser",
              "advertiser_id": advertiser_id(name), "start_time": end - days * 86400,
              "end_time": end}
    for page in range(pages):
        data = get("search", params)
        yield from data.get("data") or []
        if not data.get("has_more"):
            return
        params.update(search_id=data["search_id"], offset=(page + 1) * 12)


def day(ms):
    return datetime.fromtimestamp(ms / 1000, timezone.utc).date().isoformat()


def main(name, region, days="30", pages="2", folder="tiktok_ads"):
    os.makedirs(folder, exist_ok=True)
    with open(os.path.join(folder, "ads.csv"), "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        saved = 0
        seen = set()
        for ad in ads(name, region.upper(), int(days), int(pages)):
            if ad["id"] in seen:  # the next page can repeat an ad
                continue
            seen.add(ad["id"])
            video = ""
            for video_info in ad.get("videos") or []:  # some ads carry no video
                video = f"{ad['id']}.mp4"
                with requests.get(video_info["video_url"], headers=VIDEO_HEADERS, stream=True,
                                  timeout=120) as r:
                    r.raise_for_status()
                    with open(os.path.join(folder, video), "wb") as out:
                        for chunk in r.iter_content(1 << 16):
                            out.write(chunk)
                saved += 1
                break
            writer.writerow({"ad_id": ad["id"], "advertiser": ad["name"],
                             "title": (ad.get("title") or "").strip(),
                             "first_shown": day(ad["first_shown_date"]),
                             "last_shown": day(ad["last_shown_date"]),
                             "reach": ad.get("estimated_audience"), "video_file": video})
    print(f"{len(seen)} ads, {saved} videos saved to {folder}/")


if __name__ == "__main__":
    if len(sys.argv) < 3:
        sys.exit('usage: python tiktok_ad_videos.py "IKEA B.V." NL [days] [pages] [folder]')
    if not HEADERS["x-api-key"]:
        sys.exit("set TOOLZERHUB_API_KEY first")
    main(*sys.argv[1:])