youtube-analytics

YouTube Analytics Toolkit

Setup

Install dependencies:

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.

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:

import { analyzeChannel, searchAndAnalyze } from './scripts/src/index.js';

const analysis = await analyzeChannel('UCxxxxxxxx');

Or run directly with tsx:

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 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

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.