YouTube Analytics — CLAUDE.md

PBS YouTube channel analytics pipeline: collect data from YouTube APIs, store in SQLite, visualize with Streamlit.

Project Structure

main.py              — Click CLI entry point (init-db, seed, collect, dashboard)
src/
  auth.py            — OAuth2 authentication (YouTube Data API v3 + Analytics API v2)
  collector.py       — Data collection (videos, daily metrics, retention, traffic sources, channel stats)
  database.py        — SQLite schema (5 tables) and connection management (WAL mode, foreign keys)
  dashboard.py       — Streamlit dashboard (charts, tables, retention curves)
  seed.py            — Sample data generator (PBS plant-based cooking channel theme)
config/              — OAuth credentials (git-ignored, not committed)
data/                — SQLite database (git-ignored)

Package Manager

Uses uv (not pip, not poetry). Python >=3.12.

uv sync                          # install deps from lockfile
uv add <pkg>                     # add a dependency
uv run python main.py <command>  # run within managed venv

CLI Commands

uv run python main.py init-db-cmd   # create database tables
uv run python main.py seed          # populate with sample data
uv run python main.py collect       # pull real data (requires OAuth creds in config/)
uv run python main.py dashboard     # launch Streamlit dashboard

Database

SQLite at data/pbs_youtube.db with five tables:

videos — video metadata (id, title, published_at, duration, type)
video_daily_metrics — per-video daily stats (views, watch time, CTR, engagement)
video_retention — 100-point audience retention curves per video
video_traffic_sources — traffic source breakdown per video per day
channel_daily_metrics — channel-level daily summary

All inserts use ON CONFLICT DO UPDATE for idempotent runs.

Authentication

Real YouTube API access requires:

Create OAuth credentials at https://console.cloud.google.com/apis/credentials
Download client secret JSON → save as config/client_secret.json
First run of collect opens browser for OAuth consent, stores token at config/token.json

For development/testing, use seed command instead — no credentials needed.

Key Dependencies

click, streamlit, plotly, pandas, google-api-python-client, google-auth-oauthlib

Conventions

All data collection functions live in collector.py, one function per data type
Dashboard uses Plotly for charts via streamlit + plotly
Duration parsing handles ISO 8601 (PT1H2M3S format)
Shorts classified as videos ≤60 seconds

2.6 KiB Raw Permalink Blame History