TikTok search API: search videos by keyword to CSV

curl "https://api.toolzerhub.com/v2/tiktok/app/search/videos?keyword=skincare%20routine&count=12&region=US" \
  -H "x-api-key: $TOOLZERHUB_API_KEY"

{
  "data": {
    "search_item_list": [
      {
        "aweme_info": {
          "aweme_id": "7701302261489700148",
          "desc": "Funny,raw,unfiltered…😅Updated skincare routine🫶 telling you ",
          "create_time": 1793099174,
          "author": {
            "unique_id": "_d_vine"
          },
          "statistics": {
            "play_count": 871710,
            "digg_count": 165666,
            "comment_count": 747,
            "share_count": 913,
            "collect_count": 10705
          }
        }
      }
    ],
    "has_more": 1,
    "cursor": 12
  }
}

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

import requests

API = "https://api.toolzerhub.com/v2/tiktok/app/search/videos"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["keyword", "video_id", "author", "posted", "plays", "likes", "comments", "shares",
          "saves", "description", "url"]
calls = 0


def cell(value):
    # A leading = + - or @ would run as a formula when the CSV opens in a spreadsheet.
    return "'" + value if isinstance(value, str) and value[:1] in ("=", "+", "-", "@") else value


def get(params, tries=4):
    # 429 and 503 are worth a retry; the body or the Retry-After header says how long to wait.
    global calls
    for attempt in range(tries):
        r = requests.get(API, params=params, headers=HEADERS, timeout=120)
        calls += 1
        if r.status_code in (429, 503) and attempt < tries - 1:
            wait = int(((r.json().get("error") or {}).get("details") or {}).get("retryAfter") or r.headers.get("Retry-After") or 5 * (attempt + 1))
            time.sleep(min(wait, 60))
            continue
        r.raise_for_status()
        return r.json().get("data") or {}


def row(keyword, v):
    stats, author = v.get("statistics") or {}, v.get("author") or {}
    posted = v.get("create_time")
    return {
        "keyword": cell(keyword), "video_id": v["aweme_id"], "author": author.get("unique_id"),
        "posted": datetime.fromtimestamp(posted, timezone.utc).date().isoformat() if posted else "",
        "plays": stats.get("play_count"), "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"), "shares": stats.get("share_count"),
        "saves": stats.get("collect_count"),
        "description": cell((v.get("desc") or "").replace("\n", " ")),
        "url": f"https://www.tiktok.com/@{author.get('unique_id')}/video/{v['aweme_id']}",
    }


def search(writer, keyword, max_pages, region):
    params, seen, pages = {"keyword": keyword, "offset": "0", "count": "12", "region": region}, set(), 0
    while pages < max_pages:
        data = get(params)
        pages += 1
        for item in data.get("search_item_list") or []:
            v = item.get("aweme_info") or {}
            if v.get("aweme_id") and v["aweme_id"] not in seen:  # keep one row per video
                seen.add(v["aweme_id"])
                writer.writerow(row(keyword, v))
        cursor = data.get("cursor")
        if not data.get("has_more") or cursor is None or str(cursor) == params["offset"]:
            break
        params["offset"] = str(cursor)
    print(f"{keyword}: {len(seen)} videos in {pages} pages")
    return len(seen)


def main(keywords, max_pages="5", region="US", out="tiktok_search.csv"):
    with open(out, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        total = sum(search(writer, k.strip(), int(max_pages), region) for k in keywords.split(",") if k.strip())
    print(f"wrote {total} rows to {out} in {calls} calls")


if __name__ == "__main__":
    if not HEADERS["x-api-key"] or len(sys.argv) < 2:
        sys.exit('usage: TOOLZERHUB_API_KEY=... python tiktok_search.py "skincare routine,street food" [max_pages] [region] [file.csv]')
    main(*sys.argv[1:])

export TOOLZERHUB_API_KEY=your_key
python tiktok_search.py "skincare routine,python tutorial,street food" 10

skincare routine: 120 videos in 10 pages
python tutorial: 88 videos in 10 pages
street food: 118 videos in 10 pages
wrote 326 rows to tiktok_search.csv in 30 calls