YouTube Trending

Fetch the top trending YouTube videos using the official YouTube Data API v3. Requires a free API key (10,000 units/day free — each trending fetch costs 1 unit).

Setup: get a free API key

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable YouTube Data API v3 in the API Library
4. Go to Credentials → Create Credentials → API key
5. Set the environment variable for your platform (see below)

Setting the environment variable

macOS / Linux (bash/zsh):

export YOUTUBE_API_KEY=your_key_here

To persist across sessions, add that line to ~/.zshrc or ~/.bashrc.

Windows — Command Prompt:

set YOUTUBE_API_KEY=your_key_here

Windows — PowerShell:

$env:YOUTUBE_API_KEY = "your_key_here"

To persist in PowerShell across sessions, add it to your $PROFILE.

Usage

macOS / Linux:

python3 scripts/fetch-youtube-trending.py           # top 25, global
python3 scripts/fetch-youtube-trending.py FR        # France
python3 scripts/fetch-youtube-trending.py US 50     # top 50, US
python3 scripts/fetch-youtube-trending.py US 25 10  # Music
python3 scripts/fetch-youtube-trending.py US 25 20  # Gaming
python3 scripts/fetch-youtube-trending.py US 25 25  # News & Politics

Windows (Command Prompt or PowerShell):

python scripts/fetch-youtube-trending.py
python scripts/fetch-youtube-trending.py FR
python scripts/fetch-youtube-trending.py US 50
python scripts/fetch-youtube-trending.py US 25 10

> On Windows, python3 may not be in PATH — use python instead. Both work if Python 3 is installed.

Arguments

Category IDs

Output

For each video: rank, title, channel, duration, publish date, views, likes, comments, and a direct YouTube link.

Data source

• API: https://www.googleapis.com/youtube/v3/videos?chart=mostPopular
• Parts fetched: snippet, statistics, contentDetails
• Quota cost: 1 unit per request (free tier: 10,000 units/day)
• No pip dependencies: uses only Python stdlib (urllib, json, re)

Workflow for the AI agent

1. Check YOUTUBE_API_KEY is set; if not, guide the user through the platform-specific setup above
2. Run python3 scripts/fetch-youtube-trending.py [REGION] [COUNT] [CATEGORY] (use python on Windows if python3 is not in PATH)
3. Present the results; offer to search for more details on a specific video using WebSearch

Guardrails

• Never fabricate view counts or video titles — all data comes from the API response.
• If the API returns a 403, the key is likely invalid or the quota is exhausted for the day.
• The "global" chart (no region) reflects YouTube's default ranking, which is heavily weighted toward English-language content.