YouTube Analytics Toolkit
Setup
Install dependencies:
CODEBLOCK0
Configure credentials by creating a .env file in the project root:
CODEBLOCK1
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" | INLINECODE1 |
| "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:
CODEBLOCK2
Or run directly with tsx:
CODEBLOCK3
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: INLINECODE11
- Auto-generated: INLINECODE12
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 |
|---|
| INLINECODE14 | Full channel analysis | Channel info, recent videos, avg views per video |
| INLINECODE15 |
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 |
|---|
| INLINECODE18 | Get full channel details |
| INLINECODE19 |
Get simplified stats (subscribers, views, videoCount) |
|
getMultipleChannels(channelIds) | Batch fetch multiple channels |
Video Functions
| Function | Purpose |
|---|
| INLINECODE21 | Get full video details |
| INLINECODE22 |
Get simplified stats (views, likes, comments) |
|
getMultipleVideos(videoIds) | Batch fetch multiple videos |
|
getChannelVideos(channelId) | Get recent uploads from a channel |
Search Functions
| Function | Purpose |
|---|
| INLINECODE25 | Search for videos |
| INLINECODE26 |
Search for channels |
Results Storage
Results auto-save to results/ with this structure:
CODEBLOCK4
Managing Results
CODEBLOCK5
Tips
- 1. Use channel IDs — Channel IDs start with
UC (e.g., UCxxxxxxxx). You can find them in the channel URL or page source. - Request summaries — After pulling data, ask for a markdown summary with tables and insights.
- Compare channels — Use
compareChannels() to benchmark competitors side by side. - Batch requests — Use
getMultipleChannels() or getMultipleVideos() for efficient batch lookups. - Search + analyze —
searchAndAnalyze() combines search with full video stats in one call.
YouTube 分析工具包
设置
安装依赖项：
bash
cd scripts && npm install
在项目根目录创建 .env 文件并配置凭证：
YOUTUBEAPIKEY=AIzaSy...你的API密钥
YOUTUBEDEFAULTMAX_RESULTS=50
前置条件：一个已启用 YouTube Data API v3 的 Google Cloud 项目。从 Google Cloud 控制台 获取你的 API 密钥。
快速入门
| 用户输入 | 调用的函数 |
|---|
| 分析这个 YouTube 频道 | analyzeChannel(channelId) |
| 比较这两个频道 |
compareChannels([id1, id2]) |
| 这个视频表现如何？ | analyzeVideo(videoId) |
| 在 YouTube 上搜索 [主题] | searchAndAnalyze(query) |
| 获取这个频道的统计数据 | getChannelStats(channelId) |
| 获取这个视频的观看次数 | getVideoStats(videoId) |
| 查找关于 [主题] 的频道 | searchChannels(query) |
| 显示该频道最近的上传 | getChannelVideos(channelId) |
通过从 scripts/src/index.ts 导入来执行函数：
typescript
import { analyzeChannel, searchAndAnalyze } from ./scripts/src/index.js;
const analysis = await analyzeChannel(UCxxxxxxxx);
或直接使用 tsx 运行：
bash
npx tsx scripts/src/index.ts
工作流程模式
每次分析都遵循三个阶段：
1. 分析
运行 API 函数。每次调用都会访问 YouTube Data API 并返回结构化数据。
2. 自动保存
所有结果自动保存为 JSON 文件到 results/{category}/ 目录。文件命名模式：
- - 命名结果：{清理后的名称}.json
- 自动生成：YYYYMMDDHHMMSS_{操作}.json
3. 总结
分析完成后，读取已保存的 JSON 文件，在 results/summaries/ 目录中创建包含数据表格、比较和洞察的 markdown 摘要。
高级函数
| 函数 | 用途 | 收集内容 |
|---|
| analyzeChannel(channelId) | 完整频道分析 | 频道信息、近期视频、平均每视频观看次数 |
| compareChannels(channelIds) |
比较多个频道 | 并列显示订阅者数、观看次数、视频数量 |
| analyzeVideo(videoId) | 视频表现分析 | 观看次数、点赞数、评论数、点赞率、评论率 |
| searchAndAnalyze(query, maxResults?) | 搜索 + 统计 | 搜索结果及完整视频统计数据 |
单个 API 函数
如需精细控制，可从 API 模块导入特定函数。查看 references/api-reference.md 获取包含参数、类型和示例的完整 13 个 API 函数列表。
频道函数
| 函数 | 用途 |
|---|
| getChannel(channelId) | 获取完整频道详情 |
| getChannelStats(channelId) |
获取简化统计数据（订阅者数、观看次数、视频数量） |
| getMultipleChannels(channelIds) | 批量获取多个频道 |
视频函数
| 函数 | 用途 |
|---|
| getVideo(videoId) | 获取完整视频详情 |
| getVideoStats(videoId) |
获取简化统计数据（观看次数、点赞数、评论数） |
| getMultipleVideos(videoIds) | 批量获取多个视频 |
| getChannelVideos(channelId) | 获取频道最近上传的视频 |
搜索函数
| 函数 | 用途 |
|---|
| searchVideos(query, options?) | 搜索视频 |
| searchChannels(query, options?) |
搜索频道 |
结果存储
结果自动保存到 results/ 目录，结构如下：
results/
├── channels/ # 频道数据和比较
├── videos/ # 视频数据和分析
├── search/ # 搜索结果
└── summaries/ # 人类可读的 markdown 摘要
管理结果
typescript
import { listResults, loadResult, getLatestResult } from ./scripts/src/index.js;
// 列出最近的结果
const files = listResults(channels, 10);
// 加载特定结果
const data = loadResult(files[0]);
// 获取某个操作的最新结果
const latest = getLatestResult(channels, channel_analysis);
提示
- 1. 使用频道 ID — 频道 ID 以 UC 开头（例如 UCxxxxxxxx）。你可以在频道 URL 或页面源代码中找到它们。
- 请求摘要 — 拉取数据后，请求包含表格和洞察的 markdown 摘要。
- 比较频道 — 使用 compareChannels() 并排比较竞争对手。
- 批量请求 — 使用 getMultipleChannels() 或 getMultipleVideos() 进行高效的批量查询。
- 搜索 + 分析 — searchAndAnalyze() 在一次调用中结合搜索和完整视频统计。
