无法通过YouTube API获取视频留存数据问题求助

核心问题排查与修复步骤 #

1. 日期范围与数据延迟 #

YouTube留存数据存在聚合延迟，通常视频发布48小时后才会生成可用的留存统计，且过窄的日期范围（比如仅2天）可能因数据未完成聚合导致返回空。

• 修复：将日期范围调整为视频发布日至当前日期，或至少覆盖7天以上的周期。

2. 指标与维度的匹配规则 #

relativeRetentionPerformance指标的维度组合有严格要求，单独使用elapsedVideoTimeRatio可能触发过滤逻辑导致无数据返回。

• 修复：尝试调整维度为video,elapsedVideoTimeRatio，或暂时移除维度直接查询指标；也可换用absoluteRetentionPerformance指标做测试验证。

3. 权限范围缺失 #

若你的Access Token仅请求了YouTube Data API权限（如youtube.readonly），未包含Analytics相关权限，会导致无法读取留存数据。

• 修复：获取Token时必须包含https://www.googleapis.com/auth/yt-analytics.readonly权限范围，建议通过OAuth2完整流程重新获取授权（而非硬编码现有Token）。

4. 数据聚合阈值限制 #

YouTube对播放量极低的视频（通常播放数<10）不会生成留存统计，即使有播放记录也会因未达聚合标准返回空。

• 修复：测试播放量在数百次以上的视频，确认是否因数据量不足导致。

5. 账号与频道匹配验证 #

确保授权账号是目标视频的所属频道所有者，channel==MINE仅对当前授权账号的频道生效，若授权账号不对也会返回空数据。

• 修复：替换ids参数为具体频道ID（如channel==UCxxxxxxx），或确认授权账号的频道归属。

调整后的Python脚本示例 #

针对权限和参数问题优化后的代码：

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
import json

# 必须包含Analytics只读权限
SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly', 'https://www.googleapis.com/auth/youtube.readonly']
VIDEO_ID = '你的视频ID'

def get_credentials():
    flow = InstalledAppFlow.from_client_secrets_file(
        'client_secret.json', SCOPES)
    credentials = flow.run_local_server(port=0)
    return credentials

def get_video_info(youtube_data, video_id):
    response = youtube_data.videos().list(part='snippet', id=video_id).execute()
    if response.get('items'):
        video = response['items'][0]
        print(f'视频标题: {video["snippet"]["title"]}')
        return video
    print('未找到视频')
    return None

def get_retention_data(credentials, video_id):
    try:
        youtube_analytics = build('youtubeAnalytics', 'v2', credentials=credentials)
        youtube_data = build('youtube', 'v3', credentials=credentials)
        get_video_info(youtube_data, VIDEO_ID)

        # 扩大日期范围，覆盖视频完整生命周期
        start_date = '2023-04-01'
        end_date = '2023-12-31'
        metrics = 'relativeRetentionPerformance'
        dimensions = 'video,elapsedVideoTimeRatio'

        request = youtube_analytics.reports().query(
            ids='channel==MINE',
            startDate=start_date,
            endDate=end_date,
            metrics=metrics,
            dimensions=dimensions,
            filters=f'video=={video_id}'
        )
        response = request.execute()
        print(json.dumps(response, indent=2))
        return response
    except HttpError as e:
        print(f'错误信息: {e}')
        return None

def save_retention_data_to_file(data, filename='retention_data.json'):
    with open(filename, 'w') as f:
        json.dump(data, f, indent=2)
    print(f'数据已保存至 {filename}')

if __name__ == '__main__':
    creds = get_credentials()
    retention_data = get_retention_data(creds, VIDEO_ID)
    save_retention_data_to_file(retention_data)

内容的提问来源于stack exchange，提问作者Aaron Ho