valtterimelkko Search YouTube Videos
Search for YouTube videos using the YouTube Data API v3. Find videos by query across all of YouTube or within specific channels.
Prerequisites
YouTube API Key available in the environment or a shell startup file such as ~/.bashrc:
export YOUTUBE_API_KEY="your-api-key-here"
Get one from Google Cloud Console: Create project → Enable YouTube Data API v3 → Create API Key.
Daily quota: 10,000 units (each search ≈ 100 units, channel resolution ≈ 1 unit, playlist fetch ≈ 1 unit).
When to Use
- Search videos by topic or channel
- Filter by date, duration, sort order
- Get up to 50 results per query
Quick Start
Basic search:
python3 ./scripts/youtube_search.py --query "AI tutorials" --max-results 10
Channel-specific (if you already have the channel ID):
python3 ./scripts/youtube_search.py --query "Python" --channel-id "UC123..." --max-results 20
Parameters
| Parameter | Required | Default | Notes |
|---|---|---|---|
--query or -q |
Yes | - | Search term |
--channel-id or -c |
No | - | If provided, search only in this channel |
--max-results or -m |
No | 10 | Max 50 (preserves quota and LLM context) |
--order or -o |
No | relevance | date, rating, relevance, viewCount |
--published-after |
No | - | ISO 8601 format (e.g., "2025-01-01T00:00:00Z") |
--published-before |
No | - | ISO 8601 format |
--video-duration or -d |
No | any | any, short (<4min), medium (4-20min), long (>20min) |
Helper Scripts (API Quota Warning)
⚠️ Each helper script uses API quota. Plan carefully before running multiple times.
1. youtube_channel_id.py - Resolve @handle to Channel ID
Cost: 1 unit per resolution
python3 ./scripts/youtube_channel_id.py --handle "@MetalSole"
2. youtube_channel_videos.py - List Channel Videos
Cost: 1-2 units for channel lookup + 1 unit per ~50 videos fetched
# By handle
python3 ./scripts/youtube_channel_videos.py --handle "@MetalSole" --max-results 50
# By channel ID (saves quota - skips handle resolution)
python3 ./scripts/youtube_channel_videos.py --channel-id "UC123..." --max-results 50
# By playlist ID (cheapest - fastest method)
python3 ./scripts/youtube_channel_videos.py --playlist-id "UU123..." --max-results 50
3. youtube_channel_search.py - Search Within Channel
Cost: 1-2 units (channel lookup) + 100 units (search query)
python3 ./scripts/youtube_channel_search.py --channel-handle "@MetalSole" --query "AI"
Quota Estimation
| Operation | Cost | Purpose |
|---|---|---|
| Basic search with query | ~100 | Find videos by topic |
| Resolve handle (@MetalSole) | ~1 | Get channel ID from handle |
| Fetch 50 channel videos | ~1 | List all uploads from channel |
| Search within channel | ~100 | Find topic within specific channel |
Example cost: Searching 10 channels for videos = ~10 units. Then searching within each channel = ~1000 units total. Plan accordingly!
Output Format
Returns JSON with video metadata:
{
"success": true,
"videos": [
{
"title": "Video Title",
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"channel_title": "Channel Name",
"published_at": "2025-01-15T10:00:00Z",
"description": "..."
}
]
}
Examples
# Latest AI videos
python3 ./scripts/youtube_search.py --query "AI" --order "date" --max-results 10
# Longer-form content only (no shorts)
python3 ./scripts/youtube_search.py --query "tutorial" --video-duration "medium" --max-results 15
# Last 30 days
python3 ./scripts/youtube_search.py --query "news" --published-after "2025-11-23T00:00:00Z"
Troubleshooting
| Problem | Solution |
|---|---|
| API key not found | Make available in your environment or shell startup file: export YOUTUBE_API_KEY="key-here" |
| 403 Forbidden | Key lacks permissions. Enable YouTube Data API v3 in Google Cloud Console |
| Quota exceeded | Used 10,000 units today. Create new Google Cloud project or wait 24hrs |
| No results | Try broader query, remove date filters |
Tips for Efficient Quota Use
- Use channel_id, not handle when possible (saves resolution cost)
- Use playlist_id for channel videos (cheapest - ~1 unit instead of 100+)
- Batch operations: Plan all queries before executing to avoid re-runs
- Cache results: Save output to file to avoid re-querying same channels
- For bulk channel analysis: Prefer
youtube_channel_videos.pyoveryoutube_channel_search.py
When Quota Runs Out
If you exhaust today's quota:
- Option 1: Wait 24 hours for quota reset
- Option 2: Create new Google Cloud project with fresh quota
- Option 3: Request quota increase (takes 24-48 hours)
- Option 4: Switch to web-based channel browsing (manual, no quota cost)
Security & Limitations
- API key = read-only access to public data
- Cannot access: private videos, watch history, subscriptions
- Max 50 results per query (for context window)
- View counts/likes not included