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. 参考来源