# SKILL: YouTube Trending Video Crawler ## 概述 YouTube 热门视频数据抓取专家技能。支持通过 YouTube Data API v3 获取当日最热门视频列表,包含多地区、多分类批量获取能力。 - **ID**: youtube-crawler - **类型**: data-collection - **版本**: 1.0.0 - **状态**: training - **目标分数**: 95/100 ## 核心能力 - 获取 YouTube 当日热门视频列表 - 支持多地区批量获取 (US/JP/KR/CN/...) - 支持视频分类过滤 (Music/Gaming/Entertainment/...) - 数据导出为 JSON / CSV 格式 - 智能配额管理与错误重试机制 ## 技术实现 ### 完整代码 (Python) ```python """ YouTube Trending Video Crawler 使用 YouTube Data API v3 获取热门视频数据 """ import os import json import csv import time import logging from datetime import datetime from typing import List, Dict, Optional, Union import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry # 配置日志 logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) logger = logging.getLogger(__name__) class YouTubeTrendingCrawler: """ YouTube 热门视频爬虫 使用 YouTube Data API v3 获取当日最热门视频列表 """ # API 端点 API_BASE_URL = "https://www.googleapis.com/youtube/v3" # 视频分类映射 VIDEO_CATEGORIES = { 1: "Film & Animation", 2: "Autos & Vehicles", 10: "Music", 17: "Sports", 20: "Gaming", 22: "People & Blogs", 23: "Comedy", 24: "Entertainment", 25: "News & Politics", 27: "Education", 28: "Science & Technology", } # 常见地区代码 REGION_CODES = ["US", "JP", "KR", "CN", "GB", "DE", "FR", "IN", "BR", "RU"] def __init__(self, api_key: Optional[str] = None): """ 初始化爬虫 Args: api_key: YouTube Data API Key,默认从环境变量 YOUTUBE_API_KEY 读取 """ self.api_key = api_key or os.getenv("YOUTUBE_API_KEY") if not self.api_key: raise ValueError( "API Key 未提供。请传入 api_key 参数或设置 YOUTUBE_API_KEY 环境变量" ) # 创建带重试机制的 session self.session = requests.Session() retry_strategy = Retry( total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504], ) adapter = HTTPAdapter(max_retries=retry_strategy) self.session.mount("https://", adapter) # 配额使用统计 self.quota_used = 0 def _make_request(self, endpoint: str, params: Dict) -> Dict: """ 发送 API 请求 Args: endpoint: API 端点路径 params: 请求参数 Returns: API 响应数据 Raises: requests.exceptions.HTTPError: HTTP 错误 ValueError: API 返回错误 """ url = f"{self.API_BASE_URL}/{endpoint}" params["key"] = self.api_key try: response = self.session.get(url, params=params, timeout=30) # 处理特定错误码 if response.status_code == 403: error_data = response.json() error_reason = error_data.get("error", {}).get("errors", [{}])[0].get("reason", "") if error_reason == "quotaExceeded": raise ValueError("API 配额已耗尽,请明日再试或申请更高配额") elif error_reason in ["keyInvalid", "badRequest"]: raise ValueError(f"API Key 无效: {error_reason}") else: raise ValueError(f"访问被拒绝: {error_reason}") elif response.status_code == 429: # 配额限制或速率限制 logger.warning("触发速率限制,等待后重试...") time.sleep(5) return self._make_request(endpoint, {k: v for k, v in params.items() if k != "key"}) response.raise_for_status() # 统计配额使用 (mostPopular 请求消耗 1 unit) self.quota_used += 1 return response.json() except requests.exceptions.Timeout: raise ValueError("请求超时,请检查网络连接") except requests.exceptions.ConnectionError: raise ValueError("网络连接错误,请检查网络设置") except requests.exceptions.RequestException as e: raise ValueError(f"请求失败: {str(e)}") def get_trending( self, region_code: str = "US", category_id: Optional[int] = None, max_results: int = 50, page_token: Optional[str] = None ) -> Dict: """ 获取指定地区的热门视频 Args: region_code: ISO 3166-1 alpha-2 地区代码,如 US, JP, KR category_id: 视频分类 ID (可选) max_results: 返回结果数量 (1-50) page_token: 分页令牌 (可选) Returns: 包含视频列表和分页信息的字典 """ if not 1 <= max_results <= 50: raise ValueError("max_results 必须在 1-50 之间") params = { "part": "snippet,statistics,contentDetails", "chart": "mostPopular", "regionCode": region_code, "maxResults": max_results, } if category_id: params["videoCategoryId"] = category_id if page_token: params["pageToken"] = page_token logger.info(f"获取 {region_code} 地区热门视频 (category={category_id or 'all'})") data = self._make_request("videos", params) videos = [] for item in data.get("items", []): video_info = self.extract_video_info(item) if video_info: videos.append(video_info) result = { "region_code": region_code, "category_id": category_id, "videos": videos, "total_results": len(videos), "next_page_token": data.get("nextPageToken"), "quota_used": self.quota_used, } logger.info(f"成功获取 {len(videos)} 条视频数据") return result def extract_video_info(self, item: Dict) -> Optional[Dict]: """ 从 API 响应中提取视频信息 Args: item: API 返回的单个视频数据 Returns: 标准化的视频信息字典 """ try: video_id = item.get("id") snippet = item.get("snippet", {}) statistics = item.get("statistics", {}) thumbnails = snippet.get("thumbnails", {}) return { "videoId": video_id, "url": f"https://youtube.com/watch?v={video_id}", "title": snippet.get("title", ""), "description": snippet.get("description", ""), "channelTitle": snippet.get("channelTitle", ""), "channelId": snippet.get("channelId", ""), "publishedAt": snippet.get("publishedAt", ""), "categoryId": snippet.get("categoryId", ""), "categoryName": self.VIDEO_CATEGORIES.get( int(snippet.get("categoryId", 0)), "Unknown" ), "viewCount": int(statistics.get("viewCount", 0)), "likeCount": int(statistics.get("likeCount", 0)) if statistics.get("likeCount") else 0, "commentCount": int(statistics.get("commentCount", 0)) if statistics.get("commentCount") else 0, "duration": item.get("contentDetails", {}).get("duration", ""), "thumbnails": { "default": thumbnails.get("default", {}).get("url", ""), "medium": thumbnails.get("medium", {}).get("url", ""), "high": thumbnails.get("high", {}).get("url", ""), "standard": thumbnails.get("standard", {}).get("url", ""), "maxres": thumbnails.get("maxres", {}).get("url", ""), }, "tags": snippet.get("tags", []), "liveBroadcastContent": snippet.get("liveBroadcastContent", "none"), } except Exception as e: logger.warning(f"解析视频数据失败: {str(e)}") return None def get_multi_region_trending( self, regions: List[str], category_id: Optional[int] = None, max_results: int = 50 ) -> Dict[str, Dict]: """ 批量获取多个地区的热门视频 高效使用配额:每个地区仅消耗 1 unit Args: regions: 地区代码列表,如 ["US", "JP", "KR"] category_id: 视频分类 ID (可选) max_results: 每个地区返回结果数量 Returns: 以地区代码为键的结果字典 """ results = {} logger.info(f"开始批量获取 {len(regions)} 个地区的热门视频") for region in regions: try: result = self.get_trending( region_code=region, category_id=category_id, max_results=max_results ) results[region] = result # 请求间隔,避免触发速率限制 time.sleep(0.5) except Exception as e: logger.error(f"获取 {region} 地区数据失败: {str(e)}") results[region] = {"error": str(e), "videos": []} logger.info(f"批量获取完成,总配额使用: {self.quota_used} units") return results def get_all_categories_trending( self, region_code: str = "US", max_results: int = 50 ) -> Dict[int, Dict]: """ 获取指定地区所有分类的热门视频 Args: region_code: 地区代码 max_results: 每个分类返回结果数量 Returns: 以分类 ID 为键的结果字典 """ results = {} for category_id in self.VIDEO_CATEGORIES.keys(): try: result = self.get_trending( region_code=region_code, category_id=category_id, max_results=max_results ) results[category_id] = result time.sleep(0.5) except Exception as e: logger.error(f"获取分类 {category_id} 数据失败: {str(e)}") results[category_id] = {"error": str(e), "videos": []} return results def save_to_json( self, data: Union[Dict, List], filepath: Optional[str] = None, region: Optional[str] = None ) -> str: """ 保存数据为 JSON 文件 Args: data: 要保存的数据 filepath: 文件路径 (可选,默认自动生成) region: 地区代码 (用于生成文件名) Returns: 保存的文件路径 """ if filepath is None: timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") region_suffix = f"_{region}" if region else "" filepath = f"youtube_trending{region_suffix}_{timestamp}.json" # 确保目录存在 os.makedirs(os.path.dirname(filepath) if os.path.dirname(filepath) else ".", exist_ok=True) with open(filepath, "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) logger.info(f"数据已保存到: {filepath}") return filepath def save_to_csv( self, videos: List[Dict], filepath: Optional[str] = None, region: Optional[str] = None ) -> str: """ 保存视频列表为 CSV 文件 Args: videos: 视频数据列表 filepath: 文件路径 (可选) region: 地区代码 (用于生成文件名) Returns: 保存的文件路径 """ if filepath is None: timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") region_suffix = f"_{region}" if region else "" filepath = f"youtube_trending{region_suffix}_{timestamp}.csv" # 确保目录存在 os.makedirs(os.path.dirname(filepath) if os.path.dirname(filepath) else ".", exist_ok=True) if not videos: logger.warning("没有数据可保存") return filepath # 定义 CSV 字段 fieldnames = [ "videoId", "url", "title", "channelTitle", "channelId", "viewCount", "likeCount", "commentCount", "publishedAt", "categoryId", "categoryName", "duration", "thumbnail_high" ] with open(filepath, "w", newline="", encoding="utf-8") as f: writer = csv.DictWriter(f, fieldnames=fieldnames) writer.writeheader() for video in videos: row = { "videoId": video.get("videoId", ""), "url": video.get("url", ""), "title": video.get("title", ""), "channelTitle": video.get("channelTitle", ""), "channelId": video.get("channelId", ""), "viewCount": video.get("viewCount", 0), "likeCount": video.get("likeCount", 0), "commentCount": video.get("commentCount", 0), "publishedAt": video.get("publishedAt", ""), "categoryId": video.get("categoryId", ""), "categoryName": video.get("categoryName", ""), "duration": video.get("duration", ""), "thumbnail_high": video.get("thumbnails", {}).get("high", ""), } writer.writerow(row) logger.info(f"CSV 数据已保存到: {filepath}") return filepath def get_quota_status(self) -> Dict: """ 获取配额使用状态 Returns: 配额使用信息 """ return { "quota_used": self.quota_used, "quota_limit": 10000, "quota_remaining": 10000 - self.quota_used, "usage_percentage": (self.quota_used / 10000) * 100, } # ==================== 使用示例 ==================== def main(): """使用示例""" # 初始化爬虫 crawler = YouTubeTrendingCrawler() # 示例 1: 获取美国热门视频 print("=== 获取美国热门视频 ===") us_trending = crawler.get_trending(region_code="US", max_results=10) print(f"获取到 {us_trending['total_results']} 条视频") print(f"配额使用: {us_trending['quota_used']} units") # 示例 2: 获取日本音乐类热门视频 print("\n=== 获取日本音乐类热门视频 ===") jp_music = crawler.get_trending(region_code="JP", category_id=10, max_results=5) print(f"获取到 {jp_music['total_results']} 条音乐视频") # 示例 3: 多地区批量获取 print("\n=== 批量获取多地区热门视频 ===") multi_region = crawler.get_multi_region_trending( regions=["US", "JP", "KR"], max_results=5 ) for region, data in multi_region.items(): if "error" not in data: print(f"{region}: {data['total_results']} 条视频") # 示例 4: 保存数据 print("\n=== 保存数据 ===") crawler.save_to_json(us_trending, region="US") crawler.save_to_csv(us_trending["videos"], region="US") # 示例 5: 查看配额状态 print("\n=== 配额状态 ===") quota = crawler.get_quota_status() print(f"已使用: {quota['quota_used']}/{quota['quota_limit']} ({quota['usage_percentage']:.2f}%)") if __name__ == "__main__": main() ``` ## API 使用规范 ### 环境变量配置 ```bash export YOUTUBE_API_KEY="your_api_key_here" ``` ### 获取 API Key 1. 访问 [Google Cloud Console](https://console.cloud.google.com/) 2. 创建新项目或选择现有项目 3. 启用 **YouTube Data API v3** 4. 创建凭据 → API 密钥 5. 限制密钥使用范围(推荐) ### 关键参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `part` | string | 是 | `snippet,statistics,contentDetails` | | `chart` | string | 是 | 固定值 `mostPopular` | | `regionCode` | string | 否 | ISO 3166-1 alpha-2 代码,如 `US`, `JP`, `KR` | | `videoCategoryId` | string | 否 | 视频分类 ID | | `maxResults` | integer | 否 | 1-50,默认 5 | | `pageToken` | string | 否 | 分页令牌 | ### 配额管理 | 请求类型 | 消耗配额 | |----------|----------| | videos.list (mostPopular) | 1 unit | | 每日配额上限 | 10,000 units | **配额优化策略**: - 使用 `get_multi_region_trending()` 批量获取多个地区数据 - 合理设置 `max_results` (默认 50) - 添加缓存机制,避免频繁请求 ### 视频分类 ID 映射 | ID | 分类名称 | |----|----------| | 10 | Music | | 20 | Gaming | | 24 | Entertainment | | 28 | Science & Technology | | 1 | Film & Animation | | 17 | Sports | | 22 | People & Blogs | | 23 | Comedy | | 25 | News & Politics | | 27 | Education | ## 错误处理 ### 错误码说明 | HTTP 状态码 | 含义 | 处理方式 | |-------------|------|----------| | 200 | 成功 | 正常处理数据 | | 400 | 请求参数错误 | 检查 regionCode 是否有效 | | 403 | 权限错误 | 检查 API Key 是否有效或配额是否耗尽 | | 429 | 速率限制 | 指数退避重试 | | 500+ | 服务器错误 | 稍后重试 | ### 异常类型 ```python # 无效 API Key ValueError: API Key 无效: keyInvalid # 配额耗尽 ValueError: API 配额已耗尽,请明日再试或申请更高配额 # 网络超时 ValueError: 请求超时,请检查网络连接 ``` ## 输出数据格式 ### JSON 格式 ```json { "region_code": "US", "category_id": null, "videos": [ { "videoId": "dQw4w9WgXcQ", "url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "title": "Video Title", "description": "Video description...", "channelTitle": "Channel Name", "channelId": "UC...", "publishedAt": "2024-01-15T10:00:00Z", "categoryId": "10", "categoryName": "Music", "viewCount": 1500000, "likeCount": 50000, "commentCount": 2000, "duration": "PT3M45S", "thumbnails": { "default": "https://i.ytimg.com/vi/.../default.jpg", "medium": "https://i.ytimg.com/vi/.../mqdefault.jpg", "high": "https://i.ytimg.com/vi/.../hqdefault.jpg" }, "tags": ["tag1", "tag2"], "liveBroadcastContent": "none" } ], "total_results": 50, "next_page_token": "CA8QAA", "quota_used": 5 } ``` ### CSV 格式 ```csv videoId,url,title,channelTitle,channelId,viewCount,likeCount,commentCount,publishedAt,categoryId,categoryName,duration,thumbnail_high dQw4w9WgXcQ,https://youtube.com/watch?v=dQw4w9WgXcQ,Video Title,Channel Name,UC...,1500000,50000,2000,2024-01-15T10:00:00Z,10,Music,PT3M45S,https://i.ytimg.com/vi/.../hqdefault.jpg ``` ## 输入参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | region_code | string | 否 | "US" | 地区代码 (ISO 3166-1 alpha-2) | | category_id | integer | 否 | null | 视频分类 ID | | max_results | integer | 否 | 50 | 返回数量 (1-50) | | page_token | string | 否 | null | 分页令牌 | ## 输出字段 | 字段 | 类型 | 说明 | |------|------|------| | videoId | string | YouTube 视频 ID | | url | string | 完整视频链接 | | title | string | 视频标题 | | channelTitle | string | 频道名称 | | viewCount | integer | 播放次数 | | thumbnails | object | 各尺寸封面 URL | | publishedAt | string | 发布时间 (ISO 8601) | | categoryId | string | 视频分类 ID | | categoryName | string | 分类名称 | ## 高级用法 ### 分页获取 ```python crawler = YouTubeTrendingCrawler() # 第一页 result = crawler.get_trending(region_code="US", max_results=50) next_token = result.get("next_page_token") # 第二页 if next_token: result_page2 = crawler.get_trending( region_code="US", max_results=50, page_token=next_token ) ``` ### 全部分类获取 ```python # 获取某地区所有分类的热门视频 all_categories = crawler.get_all_categories_trending(region_code="US") for category_id, data in all_categories.items(): print(f"分类 {category_id}: {data['total_results']} 条视频") ``` ### 自定义请求参数 ```python # 只获取 snippet 部分(节省配额,但字段较少) result = crawler._make_request("videos", { "part": "snippet", "chart": "mostPopular", "regionCode": "US", "maxResults": 10 }) ``` ## 依赖安装 ```bash pip install requests urllib3 ``` ## 最佳实践 1. **API Key 安全**: 始终通过环境变量读取,不要硬编码 2. **错误处理**: 生产环境务必添加 try-except 包裹调用 3. **配额监控**: 定期检查配额使用情况,避免服务中断 4. **请求间隔**: 批量获取时添加适当延迟 (0.5-1 秒) 5. **数据缓存**: Trending 数据 15-30 分钟内变化不大,建议缓存 ## 版本历史 | 版本 | 分数 | 日期 | 主要改进 | |------|------|------|----------| | v1.0 | TBD | 2026-04-01 | 初始版本,Python 完整实现 |