Creator Discovery Engine (v1)

Automates the repetitive part of manual YouTube creator research: search a keyword, open every channel, copy subscriber counts, calculate average views, find a business email, paste it all into Excel.

Humans still evaluate every creator afterwards — this tool only collects the objective data.

What it does

1. Reads a .txt file of keywords (one search per line).
2. Runs one search.list call per keyword (no pagination by default) to find candidate video/channel results.
3. Batches channels.list calls (up to 50 IDs per call) to pull subscriber count, total views, description, country, etc.
4. Pages each channel's uploads playlist and checks video durations (batched videos.list calls) to find the 10 most recent non-Short videos.
5. Calculates average views/likes/comments, view ratio, and upload frequency from those videos.
6. Extracts a business email and website only if they appear in the channel's public description — never guessed or fabricated.
7. Writes everything to an Excel file, incrementally, after each keyword.
8. Leaves all subjective/evaluation columns (Has Ebook?, Buying Power, Total, Status, etc.) blank for you to fill in by hand.

Subscriber filter

You can set an optional min and/or max subscriber count before starting a run (blank = no limit, editable each time). It's applied right after the cheap channels.list call and before the more expensive per-channel playlist/video calls, so a tight filter also stretches your daily quota further — out-of-range channels never cost the pricier calls. Filtered-out channels aren't written to the Excel file (only "Outside subscriber range (skipped)" is incremented in the progress panel), so if you re-run with a different range later, those channels will be re-evaluated rather than permanently ignored.

Quota awareness

YouTube Data API v3 gives you 10,000 units/day by default. search.list costs 100 units; channels.list and videos.list cost ~1 unit per call (batched up to 50 IDs). Before you start a run, the UI shows an upper-bound estimate of how many units the keyword file could cost. While running, the app tracks actual units spent in real time and stops gracefully — saving everything collected so far — if it's about to run out. Re-running against the same output file resumes automatically: any Channel ID already in the spreadsheet is skipped, so you never re-spend quota on a creator you've already collected.

Setup

pip install -r requirements.txt
cp .env.example .env
# edit .env and paste in your YouTube Data API v3 key
uvicorn app.main:app --reload

Then open http://127.0.0.1:8000 in your browser.

Getting a YouTube API key: create a project in the Google Cloud Console, enable the "YouTube Data API v3", then create an API key under Credentials.

Using it

1. Select Keyword File — upload a .txt file, one search phrase per line. A sample is included at sample_keywords/career.txt.
2. Review the quota estimate, optionally set a min/max subscriber range, tick the confirmation box, and hit Start Search.
3. Watch live progress: current keyword, channels found, units spent / remaining.
4. When it finishes (or stops early because of quota), click Export Excel / Download to grab the .xlsx file.
5. To create a separate list (e.g. finance creators), just upload a different keyword file and give it a different output file name.
6. To resume an interrupted or quota-limited run, upload the same keyword file, set the same output file name, and start again — already-collected channels are skipped automatically.

Project structure

app/
  main.py          FastAPI routes (upload, estimate, start, progress, download)
  pipeline.py       Orchestrates the full search -> details -> videos -> excel flow
  youtube_api.py    YouTube Data API client, quota tracking, exponential backoff
  excel_export.py   OpenPyXL schema, incremental writes, resume/dedup
  utils.py          Email/URL regex extraction, ISO-8601 duration parsing,
                     upload-frequency calculation, keyword file parsing
  state.py          In-memory progress state for the single active run
  config.py         Loads .env, defines tunables (batch size, quota costs, etc.)
  static/           Vanilla HTML/CSS/JS frontend
data/
  keywords/         Uploaded keyword files land here
  output/           Generated Excel files land here
sample_keywords/
  career.txt        Example keyword file to try immediately

Notes & assumptions (v1, documented for transparency)

• One run at a time. This is a single-user local tool; there's no multi-run queue.
• Quota estimate is an upper bound, not an exact prediction — it assumes no duplicate channels across keywords. The number that actually protects your daily budget is the live tracker, which checks remaining quota before every batch and halts the run before it would go over.
• Website extraction ignores youtube.com / youtu.be links found in the description (those are almost never "the creator's website") and returns the first remaining URL found. If nothing is there, the field is left blank — never guessed.
• Upload frequency is based on the average number of days between the up-to-10 most recent non-Short videos: ≤3.5 days → "Multiple/week", ≤9 → "Weekly", ≤17 → "Biweekly", ≤45 → "Monthly", otherwise "Inactive". Fewer than 2 videos → "Insufficient Data".
• Shorts detection treats any video ≤60 seconds as a Short and excludes it, per YouTube not providing a direct isShort flag.