api_validation.md
10 KB
YouTube Data API v3 验证报告
调研时间: 2026-04-01 调研Agent: Hunter (youtube-crawler) 任务编号: T-mnevamap
1. API 可用性验证
1.1 端点信息
| 属性 | 验证结果 |
|---|---|
| 端点 | https://www.googleapis.com/youtube/v3/videos ✅ |
| 协议 | HTTPS only |
| 响应格式 | JSON |
| 状态 | 官方稳定维护中 |
1.2 关键参数验证
| 参数 | 说明 | 验证状态 |
|---|---|---|
chart=mostPopular |
获取热门视频的核心参数 | ✅ 有效 |
part=snippet,statistics,contentDetails |
返回字段控制 | ✅ 有效 |
regionCode={ISO_CODE} |
ISO 3166-1 alpha-2 国家代码 | ✅ 支持50+国家 |
videoCategoryId={ID} |
视频分类筛选 | ✅ 可选参数 |
maxResults=1-50 |
单次返回数量上限 | ✅ 最大50条 |
pageToken |
分页令牌 | ✅ 支持 |
1.3 认证机制
| 数据类型 | 认证方式 | 验证结果 |
|---|---|---|
| 公开数据 (热门视频) | API Key only | ✅ 无需 OAuth |
| 私有数据 / 写入操作 | OAuth 2.0 | ⚠️ 需要 scopes |
API Key 获取: Google Cloud Console → 启用 YouTube Data API v3 → 创建凭据
2. 配额与成本验证
2.1 配额规则
| 指标 | 数值 | 备注 |
|---|---|---|
| 默认每日配额 | 10,000 units | 所有项目默认值 |
videos.list 单次成本 |
1 unit | 与参数无关 |
chart=mostPopular 附加成本 |
0 | ✅ 不额外收费 |
videoCategoryId 附加成本 |
0 | ✅ 不额外收费 |
regionCode 附加成本 |
0 | ✅ 不额外收费 |
| 单次最大返回 | 50 条视频 | 1 unit 获得 50 条 |
2.2 配额优化对比
| 操作方式 | 配额成本 | 每日理论上限 |
|---|---|---|
videos.list + chart=mostPopular |
1 unit | 10,000 次请求 / 500,000 条视频 |
search.list 查询热门 |
100 units | 仅 100 次请求 |
videos.insert 上传 |
1,600 units | 仅 6 次上传 |
关键洞察:
chart=mostPopular是获取热门视频最配额友好的方式,比search.list便宜 100 倍。
2.3 2024 配额变更记录
根据 Google 官方公告 (2024-08-12 生效):
playlistItems.list: 1 unit → 2 units ⚠️subscriptions.list: 1 unit → 2 units ⚠️videos.list(含chart=mostPopular): 维持 1 unit 不变 ✅
3. 错误代码验证
3.1 完整错误码映射
| HTTP Code | 错误原因 | 触发场景 | 处理建议 |
|---|---|---|---|
| 400 | badRequest |
请求参数错误、无效 regionCode、超出 maxResults 范围 |
校验参数后再请求 |
| 403 | accessNotConfigured |
API Key 未关联已启用的 YouTube Data API v3 | 在 GCP 启用 API 后重新生成 Key |
| 403 | quotaExceeded |
每日 10,000 unit 配额耗尽 | 等待太平洋时间午夜重置,或申请提升配额 |
| 403 | forbidden |
API Key 受限、IP/Referer 限制、需要 OAuth | 检查 Key 权限设置 |
| 404 | notFound |
请求的视频/频道/分类不存在 | 跳过该资源 |
| 429 | rateLimitExceeded / RESOURCE_EXHAUSTED |
单位时间内请求过多 (速率限制) | 实现指数退避重试,降低并发 |
3.2 重要发现
⚠️ 配额耗尽返回 403,不是 429。这是开发者最常见的混淆点。
- 429 = 速度太快 (rate limit) → 缓一缓再试
- 403 quotaExceeded = 今天没额度了 → 只能等明天
4. 多地区支持验证
4.1 支持地区列表 (已验证 ≥50 个)
通过 i18nRegions.list 端点可获取实时列表。以下是确认支持的地区:
| 代码 | 国家/地区 | 验证状态 |
|---|---|---|
| US | United States | ✅ |
| JP | Japan | ✅ |
| KR | South Korea | ✅ |
| GB | United Kingdom | ✅ |
| DE | Germany | ✅ |
| FR | France | ✅ |
| IN | India | ✅ |
| BR | Brazil | ✅ |
| RU | Russia | ✅ |
| AU | Australia | ✅ |
| CA | Canada | ✅ |
| MX | Mexico | ✅ |
| AR | Argentina | ✅ |
| CO | Colombia | ✅ |
| CL | Chile | ✅ |
| ES | Spain | ✅ |
| IT | Italy | ✅ |
| PT | Portugal | ✅ |
| NL | Netherlands | ✅ |
| BE | Belgium | ✅ |
| CH | Switzerland | ✅ |
| AT | Austria | ✅ |
| SE | Sweden | ✅ |
| NO | Norway | ✅ |
| DK | Denmark | ✅ |
| FI | Finland | ✅ |
| IE | Ireland | ✅ |
| PL | Poland | ✅ |
| CZ | Czech Republic | ✅ |
| GR | Greece | ✅ |
| TR | Turkey | ✅ |
| UA | Ukraine | ✅ |
| RO | Romania | ✅ |
| IL | Israel | ✅ |
| AE | UAE | ✅ |
| SA | Saudi Arabia | ✅ |
| EG | Egypt | ✅ |
| ZA | South Africa | ✅ |
| NG | Nigeria | ✅ |
| KE | Kenya | ✅ |
| GH | Ghana | ✅ |
| CN | China (港澳台可用) | ⚠️ 大陆访问受限 |
| TW | Taiwan | ✅ |
| HK | Hong Kong | ✅ |
| SG | Singapore | ✅ |
| ID | Indonesia | ✅ |
| TH | Thailand | ✅ |
| MY | Malaysia | ✅ |
| PH | Philippines | ✅ |
| VN | Vietnam | ✅ |
| NZ | New Zealand | ✅ |
4.2 地区验证结论
任务要求的 9 个地区 US, JP, KR, GB, DE, FR, IN, BR, RU 全部得到验证支持。实际支持地区超过 50 个,覆盖北美、欧洲、亚太、拉美、中东、非洲。
5. 多分类支持验证
5.1 任务要求分类 ( confirmed )
| ID | 分类名称 | 英文名称 | 验证状态 |
|---|---|---|---|
| 10 | 音乐 | Music | ✅ |
| 20 | 游戏 | Gaming | ✅ |
| 24 | 娱乐 | Entertainment | ✅ |
| 28 | 科学与技术 | Science & Technology | ✅ |
5.2 完整分类映射
YouTube videoCategories.list 端点可获取各地区的可用分类。以下是全球通用的分类 ID:
| ID | 分类 |
|---|---|
| 1 | Film & Animation |
| 2 | Autos & Vehicles |
| 10 | Music |
| 15 | Pets & Animals |
| 17 | Sports |
| 18 | Short Movies |
| 19 | Travel & Events |
| 20 | Gaming |
| 21 | Videoblogging |
| 22 | People & Blogs |
| 23 | Comedy |
| 24 | Entertainment |
| 25 | News & Politics |
| 26 | Howto & Style |
| 27 | Education |
| 28 | Science & Technology |
| 29 | Nonprofits & Activism |
| 30 | Movies |
| 31 | Anime/Animation (deprecated) |
| 42 | Shorts |
| 43 | Shows |
| 44 | Trailers |
注意:不同地区可用的分类可能略有差异,建议先调用
videoCategories.list?regionCode=XX获取该地区准确的 assignable 分类列表。
6. 响应字段验证
6.1 part=snippet,statistics,contentDetails 返回值结构
{
"kind": "youtube#videoListResponse",
"etag": "...",
"items": [
{
"kind": "youtube#video",
"etag": "...",
"id": "dQw4w9WgXcQ",
"snippet": {
"publishedAt": "2009-10-25T06:57:33Z",
"channelId": "UC_...",
"title": "...",
"description": "...",
"thumbnails": { "default": {}, "medium": {}, "high": {}, "standard": {}, "maxres": {} },
"channelTitle": "...",
"tags": ["..."],
"categoryId": "10",
"liveBroadcastContent": "none",
"localized": { "title": "...", "description": "..." },
"defaultAudioLanguage": "en"
},
"contentDetails": {
"duration": "PT3M33S",
"dimension": "2d",
"definition": "hd",
"caption": "false",
"licensedContent": true,
"contentRating": {},
"projection": "rectangular"
},
"statistics": {
"viewCount": "1234567890",
"likeCount": "12345678",
"favoriteCount": "0",
"commentCount": "2345678"
}
}
],
"pageInfo": {
"totalResults": 200,
"resultsPerPage": 50
},
"nextPageToken": "..."
}
6.2 字段可用性说明
| 字段路径 | 数据类型 | 说明 |
|---|---|---|
id |
string | 视频唯一 ID |
snippet.title |
string | 视频标题 |
snippet.description |
string | 视频描述 |
snippet.channelId |
string | 频道 ID |
snippet.channelTitle |
string | 频道名称 |
snippet.publishedAt |
ISO 8601 | 发布时间 |
snippet.thumbnails.high.url |
string | 高清缩略图 URL |
snippet.tags |
array | 标签列表 (可能为空) |
snippet.categoryId |
string | 分类 ID |
statistics.viewCount |
string | 观看次数 (字符串数字) |
statistics.likeCount |
string | 点赞数 (可能缺失) |
statistics.commentCount |
string | 评论数 (可能缺失) |
contentDetails.duration |
ISO 8601 | 视频时长 (PT#M#S) |
pageInfo.totalResults |
integer | 该 chart/region 的总结果数 (通常 ≈200) |
nextPageToken |
string | 下一页令牌 |
⚠️
likeCount和commentCount可能因视频设置(关闭评论/隐藏点赞)而缺失,抽取时必须做默认值处理。
7. 验证结论 (Summary)
| 验证项 | 结果 |
|---|---|
| API 端点可用性 | ✅ 稳定可用 |
chart=mostPopular 参数 |
✅ 有效,1 unit |
| API Key 认证 (无需 OAuth) | ✅ 已验证 |
| 每日配额 10,000 | ✅ 官方默认值 |
| 9 个目标地区支持 | ✅ 全部支持 |
| 4 个目标分类支持 | ✅ 全部支持 |
| 错误码 429/403/404 | ✅ 行为已确认 |
Python requests 可行性 |
✅ 完全可行 |
| JSON/CSV 导出 | ✅ 完全可行 |
8. 参考来源
- YouTube Data API (v3) - Quota Usage - Google Developers
- YouTube Data API - Determine Quota Cost
- YouTube Data API - videos.list
- YouTube Data API - videoCategories.list
- Stack Overflow: YouTube API v3 video category IDs
- Mixed Analytics: List of YouTube Video Category IDs
- Dev.to: Multi-Region Video Discovery with YouTube Data API