youtube-analytics

# YouTube Analytics Toolkit ## Setup Install dependencies: ```bash cd scripts && npm install ``` Configure credentials by creating a `.env` file in the project root: ``` YOUTUBE_API_KEY=AIzaSy...your-api-key YOUTUBE_DEFAULT_MAX_RESULTS=50 ``` **Prerequisites**: A Google Cloud project with the YouTube Data API v3 enabled. Get your API key from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). ## Quick Start | User says | Function to call | |-----------|-----------------| | "Analyze this YouTube channel" | `analyzeChannel(channelId)` | | "Compare these two channels" | `compareChannels([id1, id2])` | | "How is this video performing?" | `analyzeVideo(videoId)` | | "Search YouTube for [topic]" | `searchAndAnalyze(query)` | | "Get stats for this channel" | `getChannelStats(channelId)` | | "Get this video's view count" | `getVideoStats(videoId)` | | "Find channels about [topic]" | `searchChannels(query)` | | "Show recent uploads from this channel" | `getChannelVideos(channelId)` | Execute functions by importing from `scripts/src/index.ts`: ```typescript import { analyzeChannel, searchAndAnalyze } from './scripts/src/index.js'; const analysis = await analyzeChannel('UCxxxxxxxx'); ``` Or run directly with tsx: ```bash npx tsx scripts/src/index.ts ``` ## Workflow Pattern Every analysis follows three phases: ### 1. Analyze Run API functions. Each call hits the YouTube Data API and returns structured data. ### 2. Auto-Save All results automatically save as JSON files to `results/{category}/`. File naming patterns: - Named results: `{sanitized_name}.json` - Auto-generated: `YYYYMMDD_HHMMSS__{operation}.json` ### 3. Summarize After analysis, read the saved JSON files and create a markdown summary in `results/summaries/` with data tables, comparisons, and insights. ## High-Level Functions | Function | Purpose | What it gathers | |----------|---------|----------------| | `analyzeChannel(channelId)` | Full channel analysis | Channel info, recent videos, avg views per video | | `compareChannels(channelIds)` | Compare multiple channels | Side-by-side subscribers, views, video counts | | `analyzeVideo(videoId)` | Video performance analysis | Views, likes, comments, like rate, comment rate | | `searchAndAnalyze(query, maxResults?)` | Search + stats | Search results with full video statistics | ## Individual API Functions For granular control, import specific functions from the API modules. See [references/api-reference.md](references/api-reference.md) for the complete list of 13 API functions with parameters, types, and examples. ### Channel Functions | Function | Purpose | |----------|---------| | `getChannel(channelId)` | Get full channel details | | `getChannelStats(channelId)` | Get simplified stats (subscribers, views, videoCount) | | `getMultipleChannels(channelIds)` | Batch fetch multiple channels | ### Video Functions | Function | Purpose | |----------|---------| | `getVideo(videoId)` | Get full video details | | `getVideoStats(videoId)` | Get simplified stats (views, likes, comments) | | `getMultipleVideos(videoIds)` | Batch fetch multiple videos | | `getChannelVideos(channelId)` | Get recent uploads from a channel | ### Search Functions | Function | Purpose | |----------|---------| | `searchVideos(query, options?)` | Search for videos | | `searchChannels(query, options?)` | Search for channels | ## Results Storage Results auto-save to `results/` with this structure: ``` results/ ├── channels/ # Channel data and comparisons ├── videos/ # Video data and analyses ├── search/ # Search results └── summaries/ # Human-readable markdown summaries ``` ### Managing Results ```typescript import { listResults, loadResult, getLatestResult } from './scripts/src/index.js'; // List recent results const files = listResults('channels', 10); // Load a specific result const data = loadResult(files[0]); // Get most recent result for an operation const latest = getLatestResult('channels', 'channel_analysis'); ``` ## Tips 1. **Use channel IDs** — Channel IDs start with `UC` (e.g., `UCxxxxxxxx`). You can find them in the channel URL or page source. 2. **Request summaries** — After pulling data, ask for a markdown summary with tables and insights. 3. **Compare channels** — Use `compareChannels()` to benchmark competitors side by side. 4. **Batch requests** — Use `getMultipleChannels()` or `getMultipleVideos()` for efficient batch lookups. 5. **Search + analyze** — `searchAndAnalyze()` combines search with full video stats in one call.