TikTok Trend Finder - Plan

tiktok-trend-finder-plan.md

TikTok Trend Finder — Plan

1. Problem Statement

There's no easy, free way to find the top trending TikTok videos for a specific keyword (like "iOS app demo") on a given day, with direct links. TikTok's own tools only filter by broad categories, not custom search terms. Swap needs this to research trending content in specific niches for marketing and content strategy.

2. Solution Overview

A Python CLI tool called tiktok-trend-finder that takes a search query, calls the TokInsight API (free tier, 2000 calls/day, no credit card), and returns the top N trending TikTok videos sorted by view count — each with title, views, likes, and a direct TikTok link. If TokInsight search is insufficient, the tool swaps to davidteather/TikTok-Api (Playwright-based) as a fallback.

3. Comparison Table

Option	Cost	Setup	Keyword Search	View Sort	Direct Links
TikTok Creative Center	Free	None	No (broad categories only)	No	Yes
TokInsight API	Free (2000/day)	RapidAPI key	Yes	Yes (in response)	Yes
davidteather/TikTok-Api	Free	Python + Playwright	Yes	Yes (manual sort)	Yes
Apify TikTok Scraper	$5/mo free tier	Account	Yes	Yes	Yes

Chosen: TokInsight API as primary (simplest, free, keyword search). davidteather/TikTok-Api as fallback.

4. User Flow

1. User installs dependencies: pip install -r requirements.txt
2. User sets RapidAPI key in .env file (one-time setup)
3. User runs: python finder.py "iOS app demo"
4. Tool calls TokInsight search endpoint with query
5. Tool sorts results by view count (descending)
6. Tool prints formatted list: rank, title, views, likes, TikTok URL
7. User clicks any link to watch the video on TikTok

5. Scope

P0 — Must Have

• CLI accepts a search query string as argument
• Calls TokInsight API and returns video results
• Each result displays: title, view count, like count, direct TikTok URL
• Results sorted by view count (highest first)
• --count N flag to control number of results (default: 10)
• --days N flag to filter by recency (default: 7 days)
• Clear error messages for: missing API key, no results found, API rate limit exceeded
• .env file support for API key
• README with setup instructions (get RapidAPI key, install deps, usage examples)

P1 — Should Have

• --output json flag for machine-readable output
• --hashtag mode to search by hashtag instead of keyword
• Colored terminal output for better readability

Out of Scope (v2+)

• Web UI or dashboard
• Scheduled/automated runs (cron)
• Video downloading
• Database or local storage
• Posting or engagement features
• Multiple API provider switching at runtime

6. Risks & Mitigations

Risk	Impact	Mitigation
TokInsight search returns poor/irrelevant results	High	Test during implementation; swap to davidteather/TikTok-Api if quality is bad
TokInsight API goes down or changes endpoints	Medium	Modular API client — swap provider with minimal code changes
RapidAPI signup has friction or requires payment	Low	Document exact signup steps in README; TokInsight free tier is well-established
TikTok video links expire or change format	Low	Use standard TikTok URL format; links are permanent
Rate limit hit (2000/day)	Low	Each search = 1 call; would need 2000 searches/day to hit limit

7. Success Criteria

Core Functionality

• python finder.py "iOS app demo" returns 10 video results
• Each result shows: title, view count, like count, direct TikTok URL
• Results are sorted by view count, highest first
• TikTok URLs are valid and open the correct video in a browser

CLI Options

• --count 5 returns exactly 5 results
• --days 3 only returns videos from the last 3 days
• --count and --days can be combined
• Default behavior (no flags) returns 10 results from last 7 days

Error Handling

• Missing API key shows message: "Set RAPIDAPI_KEY in .env file"
• No results found shows message: "No videos found for [query]"
• API error shows the HTTP status and a human-readable message

Setup & Documentation

• README explains how to get a free RapidAPI key (step by step)
• README shows install and usage examples
• .env.example contains the key placeholder
• pip install -r requirements.txt installs all dependencies without errors

8. End-to-End Test List

• E2E-1: Fresh install — clone repo, install deps, set API key, run python finder.py "iOS app demo" — get 10 results with valid TikTok links
• E2E-2: Custom count — run python finder.py "cooking tutorial" --count 3 — get exactly 3 results
• E2E-3: Recency filter — run python finder.py "fitness" --days 1 — all results are from today or yesterday
• E2E-4: No results — run python finder.py "xyznonexistenttopic999" — get friendly "no results" message
• E2E-5: Missing API key — remove .env, run finder.py — get clear error about setting the key
• E2E-6: Link validation — open the first 3 TikTok URLs from results in a browser — all load the correct video

9. Manual Testing Checklist

Smoke Test (2 min)

• python finder.py "trending" returns results
• Output shows title, views, likes, URL for each result
• First URL opens a real TikTok video

Feature Test (5 min)

• Try 3 different search queries — all return relevant results
• --count 1 returns exactly 1 result
• --count 20 returns 20 results (or all available if fewer)
• --days 1 returns only recent videos
• --days 30 returns a broader set

Error & Edge Cases (2 min)

• Empty query string shows usage help
• Very long query string doesn't crash
• No internet connection shows connection error
• Invalid API key shows authentication error