#!/usr/bin/env python3 """ yt_scanner.py - find YouTube videos that are beating their channel's size. Uses the official YouTube Data API v3 with a free API key (public data only). No pip install needed: standard library only (Python 3.9+). 1. Put your key in an environment variable: Windows PowerShell: $env:YT_API_KEY = "AIza..." macOS / Linux: export YT_API_KEY="AIza..." 2. Run: python yt_scanner.py # default queries, last 10 days, long videos python yt_scanner.py --days 7 --duration medium --median python yt_scanner.py --queries "ocean mysteries,lost civilizations" --pages 2 python yt_scanner.py --from-json saved.json # re-rank data you already collected python yt_scanner.py --max-subs 20000 --min-views 50000 --sort views_per_sub Ranking columns: views/day = views / days since upload views/sub = views / channel subscribers (a small channel with a huge video = a pattern worth studying) x_median = views / median views of the channel's last 10 uploads (only with --median) Quota (default project, Nov 2026): 100 search.list calls per day in their own bucket, plus 10,000 units per day for everything else (videos.list / channels.list / playlistItems.list = 1 unit per call). This script prints how much it used. Quotas reset at midnight Pacific Time. """ import argparse, csv, json, os, re, statistics, sys, time import urllib.parse, urllib.request, urllib.error from datetime import datetime, timedelta, timezone API = "https://www.googleapis.com/youtube/v3/" DEFAULT_QUERIES = [ "wildlife documentary", "animal documentary", "ocean mysteries", "deep sea creatures", "lost civilizations", "ancient history documentary", "survival story", "nature documentary", ] USED = {"search": 0, "units": 0} def call(endpoint, key, **params): """GET one API endpoint and return parsed JSON. Counts quota as it goes.""" params["key"] = key url = API + endpoint + "?" + urllib.parse.urlencode(params) for attempt in range(3): try: with urllib.request.urlopen(url, timeout=30) as r: data = json.loads(r.read().decode("utf-8")) if endpoint == "search": USED["search"] += 1 else: USED["units"] += 1 return data except urllib.error.HTTPError as e: body = e.read().decode("utf-8", "ignore") if e.code == 403 and "quota" in body.lower(): sys.exit("Quota exhausted for today. It resets at midnight Pacific Time. Try fewer --pages or queries.") if e.code in (400, 403): sys.exit(f"API error {e.code}: {body[:400]}\nCheck that the key is right and YouTube Data API v3 is enabled.") if attempt == 2: raise time.sleep(2 * (attempt + 1)) except urllib.error.URLError: if attempt == 2: raise time.sleep(2 * (attempt + 1)) def chunks(items, n=50): for i in range(0, len(items), n): yield items[i:i + n] def iso_duration_to_seconds(d): m = re.fullmatch(r"P(?:(\d+)D)?T?(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?", d or "") if not m: return 0 days, h, mi, s = (int(x or 0) for x in m.groups()) return days * 86400 + h * 3600 + mi * 60 + s def search_ids(key, queries, days, pages, duration, region, lang): after = (datetime.now(timezone.utc) - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ") ids = [] for q in queries: token, got = None, 0 for _ in range(pages): p = dict(part="snippet", q=q, type="video", order="viewCount", publishedAfter=after, maxResults=50, videoDuration=duration, regionCode=region, relevanceLanguage=lang) if token: p["pageToken"] = token data = call("search", key, **p) new = [it["id"]["videoId"] for it in data.get("items", []) if it.get("id", {}).get("videoId")] ids += new got += len(new) token = data.get("nextPageToken") if not token: break print(f" search {q:<32} {got:>4} results", file=sys.stderr) return list(dict.fromkeys(ids)) # de-duplicate, keep order def fetch_videos(key, ids): out = {} for batch in chunks(ids): data = call("videos", key, part="snippet,statistics,contentDetails", id=",".join(batch)) for v in data.get("items", []): st, sn = v.get("statistics", {}), v.get("snippet", {}) out[v["id"]] = { "video_id": v["id"], "title": sn.get("title", ""), "channel_id": sn.get("channelId", ""), "channel": sn.get("channelTitle", ""), "published": sn.get("publishedAt", ""), "views": int(st.get("viewCount", 0) or 0), "likes": int(st.get("likeCount", 0) or 0), "comments": int(st.get("commentCount", 0) or 0), "duration_min": round(iso_duration_to_seconds(v.get("contentDetails", {}).get("duration")) / 60, 1), } return out def fetch_channels(key, channel_ids): out = {} for batch in chunks(channel_ids): data = call("channels", key, part="statistics,contentDetails", id=",".join(batch)) for c in data.get("items", []): st = c.get("statistics", {}) out[c["id"]] = { "subs": None if st.get("hiddenSubscriberCount") else int(st.get("subscriberCount", 0) or 0), "channel_videos": int(st.get("videoCount", 0) or 0), "uploads": c.get("contentDetails", {}).get("relatedPlaylists", {}).get("uploads"), } return out def channel_medians(key, channels, last_n=10): """Median views of each channel's last N uploads (1 playlistItems call per channel + batched videos.list).""" recent = {} for cid, c in channels.items(): if not c.get("uploads"): continue try: data = call("playlistItems", key, part="contentDetails", playlistId=c["uploads"], maxResults=last_n) except urllib.error.HTTPError: continue recent[cid] = [it["contentDetails"]["videoId"] for it in data.get("items", [])] all_ids = [v for ids in recent.values() for v in ids] views = {} for batch in chunks(all_ids): data = call("videos", key, part="statistics", id=",".join(batch)) for v in data.get("items", []): views[v["id"]] = int(v.get("statistics", {}).get("viewCount", 0) or 0) return {cid: statistics.median([views[v] for v in ids if v in views]) for cid, ids in recent.items() if any(v in views for v in ids)} def rank(rows, sort_key="views_per_sub", now=None): now = now or datetime.now(timezone.utc) for r in rows: pub = datetime.fromisoformat(r["published"].replace("Z", "+00:00")) age = max((now - pub).total_seconds() / 86400, 0.25) # avoid dividing by ~0 for brand-new uploads r["age_days"] = round(age, 1) r["views_per_day"] = round(r["views"] / age) subs = r.get("subs") r["views_per_sub"] = round(r["views"] / max(subs, 1), 1) if subs is not None else None med = r.get("channel_median") r["x_median"] = round(r["views"] / max(med, 1), 1) if med else None r["url"] = "https://www.youtube.com/watch?v=" + r["video_id"] rows = [r for r in rows if r.get(sort_key) is not None] return sorted(rows, key=lambda r: r[sort_key], reverse=True) def short(n): if n is None: return "-" for unit, size in (("M", 1e6), ("k", 1e3)): if n >= size: return f"{n / size:.1f}{unit}" return str(int(n)) def print_table(rows, top, sort_key): print(f"\nTop {min(top, len(rows))} by {sort_key} (of {len(rows)} videos)\n") print(f"{'#':>3} {'score':>8} {'views':>7} {'subs':>7} {'v/day':>7} {'min':>5} channel / title") for i, r in enumerate(rows[:top], 1): score = r[sort_key] print(f"{i:>3} {short(score) if score >= 1000 else score:>8} {short(r['views']):>7} {short(r.get('subs')):>7} " f"{short(r['views_per_day']):>7} {r['duration_min']:>5} {r['channel'][:22]} | {r['title'][:60]}") def main(): for stream in (sys.stdout, sys.stderr): # Windows consoles choke on emoji in titles try: stream.reconfigure(errors="replace") except Exception: pass ap = argparse.ArgumentParser(description="Rank recent YouTube videos by how much they out-perform their channel.") ap.add_argument("--key", default=os.environ.get("YT_API_KEY"), help="API key (default: env YT_API_KEY)") ap.add_argument("--queries", help="comma-separated search terms, or a .txt file with one per line") ap.add_argument("--days", type=int, default=10, help="only videos published in the last N days (default 10)") ap.add_argument("--pages", type=int, default=2, help="search pages of 50 per query (default 2 = up to 100)") ap.add_argument("--duration", default="long", choices=["any", "short", "medium", "long"], help="short <4 min, medium 4-20 min, long >20 min (default long)") ap.add_argument("--region", default="US") ap.add_argument("--lang", default="en") ap.add_argument("--min-views", type=int, default=5000, help="ignore videos below N views (filters tiny-channel noise, default 5000)") ap.add_argument("--max-subs", type=int, default=0, help="keep only channels with at most N subscribers (0 = no limit)") ap.add_argument("--median", action="store_true", help="also compute views / channel median of last 10 uploads (costs more units)") ap.add_argument("--sort", default="views_per_sub", choices=["views_per_sub", "views_per_day", "x_median", "views"]) ap.add_argument("--top", type=int, default=30) ap.add_argument("--out", default="scan_results.csv") ap.add_argument("--save-json", help="also save the raw rows as JSON (re-rank later with --from-json)") ap.add_argument("--from-json", help="skip the API and rank rows from a JSON file") a = ap.parse_args() t0 = time.time() if a.from_json: with open(a.from_json, encoding="utf-8") as f: rows = json.load(f) else: if not a.key: sys.exit("No API key. Set YT_API_KEY or pass --key. (Google Cloud console > APIs & Services > Credentials)") if a.queries and os.path.isfile(a.queries): with open(a.queries, encoding="utf-8") as f: queries = [l.strip() for l in f if l.strip()] else: queries = [q.strip() for q in (a.queries or ",".join(DEFAULT_QUERIES)).split(",") if q.strip()] if len(queries) * a.pages > 100: sys.exit("That is more than 100 search calls, the default daily search quota. Use fewer queries or --pages.") print(f"Scanning {len(queries)} queries, last {a.days} days, duration={a.duration} ...", file=sys.stderr) ids = search_ids(a.key, queries, a.days, a.pages, a.duration, a.region, a.lang) videos = fetch_videos(a.key, ids) channels = fetch_channels(a.key, list({v["channel_id"] for v in videos.values()})) medians = channel_medians(a.key, channels) if a.median else {} rows = [] for v in videos.values(): c = channels.get(v["channel_id"], {}) v["subs"] = c.get("subs") v["channel_videos"] = c.get("channel_videos") v["channel_median"] = medians.get(v["channel_id"]) rows.append(v) if a.save_json: with open(a.save_json, "w", encoding="utf-8") as f: json.dump(rows, f, ensure_ascii=False, indent=1) rows = [r for r in rows if r.get("views", 0) >= a.min_views] if a.max_subs: rows = [r for r in rows if r.get("subs") is not None and r["subs"] <= a.max_subs] ranked = rank(rows, a.sort) print_table(ranked, a.top, a.sort) cols = ["video_id", "title", "channel", "subs", "channel_videos", "published", "age_days", "duration_min", "views", "likes", "comments", "views_per_day", "views_per_sub", "channel_median", "x_median", "url"] with open(a.out, "w", newline="", encoding="utf-8-sig") as f: w = csv.DictWriter(f, fieldnames=cols, extrasaction="ignore") w.writeheader() w.writerows(ranked) print(f"\nSaved {len(ranked)} rows to {a.out} | {time.time() - t0:.0f}s | " f"quota used: {USED['search']} search calls + {USED['units']} units", file=sys.stderr) if __name__ == "__main__": main()