/youtube-data

name: youtube-data
description: "Retrieve YouTube data using the YouTube Data API. Use when you need to search videos, get video or channel details, fetch transcripts, read comments, find trending or related content, or when the user mentions 'YouTube data', 'video stats', 'transcript', or 'channel info'."

YouTube Data

Retrieve data from the YouTube Data API v3. Supports searching videos, fetching video/channel details, reading transcripts and comments, and discovering trending or related content.

**Core principle:** Data retrieval only — this skill fetches and returns structured data. It does not produce written content or visual assets.

When to Use

• Search YouTube for videos matching a query or criteria
• Get detailed statistics for a specific video or channel
• Fetch video transcripts/captions for analysis
• Read and analyze video comments
• Find videos related to a specific video
• Discover trending videos by region
• Extract enhanced transcripts with time filtering, search, and segmentation

Prerequisites

• `YOUTUBE_API_KEY` — Set in environment or `~/.claude/.env`. Get from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
• [`uv`](https://docs.astral.sh/uv/) (recommended) or Python 3.10+ with dependencies installed

**With `uv` (recommended — zero setup):** Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use `uv run`.

**With pip (fallback):**

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

Quick Start

Search for videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "python tutorial" --max-results 5

Get video details:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py video "dQw4w9WgXcQ"

Get transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

Get channel info:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

Get comments:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

Find related videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

Get trending videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py trending --region US --max-results 10

Enhanced multi-video transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

Script Reference

`scripts/youtube_api.py`

Self-contained YouTube Data API script with 8 subcommands.

Subcommands

| Subcommand | Description | |---|---| | `search` | Search for YouTube videos with advanced filtering | | `video` | Get detailed information about a video | | `channel` | Get detailed information about a channel | | `comments` | Get comments for a video | | `transcript` | Get transcript/captions for a video | | `related` | Get videos related to a specific video | | `trending` | Get trending videos by region | | `enhanced-transcript` | Advanced multi-video transcript with filtering |

`search`

youtube_api.py search QUERY [OPTIONS]

Arguments:
  QUERY                          Search query string

Options:
  --max-results N                Number of results (default: 10, max: 50)
  --channel-id ID                Filter by channel
  --order ORDER                  Sort: date, rating, viewCount, relevance, title
  --duration DURATION            Filter: short (<4min), medium (4-20min), long (>20min)
  --published-after DATE         ISO date filter (e.g. 2024-01-01T00:00:00Z)
  --published-before DATE        ISO date filter
  --region CODE                  ISO country code (e.g. US, GB, JP)

`video`

youtube_api.py video VIDEO_ID

Returns: title, description, publish date, channel, tags, view/like/comment counts, duration, thumbnails.

`channel`

youtube_api.py channel CHANNEL_ID

Returns: title, description, subscriber/video/view counts, custom URL, thumbnails.

`comments`

youtube_api.py comments VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of comments (default: 20)
  --order ORDER                  Sort: relevance (default) or time
  --include-replies              Include reply threads
  --page-token TOKEN             Pagination token

`transcript`

youtube_api.py transcript VIDEO_ID [OPTIONS]

Options:
  --language CODE                Language code (e.g. en, ko, fr)

Returns: timestamped segments and full text with timestamps.

`related`

youtube_api.py related VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of results (default: 10)

`trending`

youtube_api.py trending [OPTIONS]

Options:
  --region CODE                  ISO country code (default: US)
  --max-results N                Number of results (default: 5)

`enhanced-transcript`

youtube_api.py enhanced-transcript VIDEO_ID [VIDEO_ID...] [OPTIONS]

Arguments:
  VIDEO_IDS                      One or more video IDs (max 5)

Options:
  --language CODE                Language code
  --format FORMAT                Output: raw, timestamped (default), merged
  --start-time SECONDS           Filter from this time
  --end-time SECONDS             Filter until this time
  --search QUERY                 Search within transcript text
  --case-sensitive               Case-sensitive search
  --segment-method METHOD        Segmentation: equal (default), smart
  --segment-count N              Number of segments (default: 1)
  --include-metadata             Include video details with transcript

Return Structure

All subcommands output JSON to stdout with this consistent structure:

{
  "success": true,
  "data": { ... },
  "error": null,
  "metadata": {
    "timestamp": "2025-01-26T12:00:00",
    ...
  }
}

On failure, `succ