此页面列出了频道所有者可以使用 YouTube Analytics API 检索的报告。频道报告提供指定频道的用户活动指标,以及视频观看次数、评分和订阅数等指标。
检索报告
要检索渠道报告,您必须在 API 请求中将 ids
参数值设为以下值之一:
-
channel==MINE
- API 会返回已通过身份验证的用户的 YouTube 频道的数据。
-
channel==CHANNEL_ID
- 将 CHANNEL_ID
设置为您要检索数据的渠道的唯一渠道 ID。授权请求的用户必须是频道的所有者。
渠道 ID 目前是一个以字母 UC
开头的字符串,不过其格式可能会发生变化。(您可以在 YouTube 频道的高级帐号设置页面上找到自己的频道 ID,也可以使用 YouTube Data API's channels.list
方法以编程方式检索您的频道 ID。)
授权
所有 YouTube Analytics API 请求都必须获得授权。授权指南介绍了如何使用 OAuth 2.0 协议检索授权令牌。
YouTube 数据分析 API 请求使用以下授权范围:
权限范围 |
https://www.googleapis.com/auth/yt-analytics.readonly |
查看有关您的 YouTube 内容的 YouTube 数据分析报告。通过此范围,您可以访问用户活动指标,例如观看次数和评分计数。 |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
查看 YouTube 分析工具为您的 YouTube 内容出具的财务报告。通过此范围,您可以访问用户活动指标,以及估算收入和广告效果指标。 |
https://www.googleapis.com/auth/youtube |
管理您的 YouTube 帐号。在 YouTube Analytics API 中,频道所有者使用此范围管理 YouTube 数据分析组和组项。 |
https://www.googleapis.com/auth/youtubepartner |
在 YouTube 上查看和管理 YouTube 资产和相关内容。在 YouTube Analytics API 中,内容所有者使用此范围管理 YouTube 数据分析组和组项。 |
注意:目前,渠道报告不支持估算收入和广告效果指标。因此,https://www.googleapis.com/auth/yt-analytics-monetary.readonly
范围当前未授予对这些报告中的货币数据的访问权限。
过滤条件
解释受支持报告的表格将列出可用于各个报告的过滤器。在表格中,括号中显示的过滤条件是可选的。例如,对于过滤选项 video(,country)
,必须提供视频过滤条件,国家/地区过滤条件是可选的。
该 API 还支持为 video
和 playlist
过滤条件指定多个值。如果您确实为这些过滤器之一指定了多个值,还可以将相应过滤器添加到您为请求指定的维度列表中。即使该过滤条件未被列为特定报表支持的维度,也是如此。
如需查看有关如何过滤特定值或值集的 API 结果的完整说明,请参阅 filters
参数定义。
了解报告表格
本部分介绍定义 API 支持的报告的表中使用的格式和术语。下表列出了基于时间的频道播放列表报告支持的维度、指标和过滤条件:
表格中有两行显示维度、一行显示指标和四行显示过滤条件。对于维度和过滤条件,只要符合表格中的使用规则,就能在 API 请求中合并每行中的值。例如,此报告的有效 dimensions
参数值包括:
dimensions=day
dimensions=7DayTotals,subscribedStatus
dimensions=30DayTotals,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
不过,参数值 day,month
无效,原因是它使用了两个基于时间的维度,但该请求必须恰好使用 1 个维度。在这种情况下,参数值 subscribedStatus,youtubeProduct
确实会返回报告,但不会按天、周、月等汇总指标。(文档中单独记录了此报告。)
报告表格术语
表使用以下术语来指明维度是必填还是选填:
- 这些字词表示必须输入值:
- 必需:您必须添加此值。
- 使用正好 1:您必须添加一个来自组的值。
- 使用 1 个或多个:您可以添加组中的任意或所有值,但必须至少包含一个。
- 这些字词表示值是可选的:
- 可选:您可以选择添加该值。
- 使用 0 或 1:您可以选择添加组中的一个值。
- 使用 0 个或更多:您可以选择添加组中的任意或所有值。
视频报告
基本统计信息
基本的用户活动统计信息
此报告可提供有关用户在频道上的操作的统计信息。您可以过滤报告,以便仅返回特定视频或国家/地区的数据。
美国各州的基本用户活动统计信息
该报告会提供美国特定州或哥伦比亚特区的统计数据。请注意,此报告仅支持上述特定国家/地区报告中可用的部分指标。
基于时间
用户在特定时间段内按国家/地区统计的活动
此报告可提供有关频道在特定时段内的用户操作的统计信息。您可以过滤报告,以便仅返回特定视频或国家/地区的数据。
美国用户在特定时间段内的活动
该报告会提供美国特定州或哥伦比亚特区的用户活动统计信息。请注意,此报告仅支持上述特定国家/地区报告中可用的部分指标。
用户地理位置
用户活动(按国家/地区划分)
此报告可按国家/地区提供频道相关的用户活动统计信息。您可以过滤报告,以便仅返回特定视频的数据。
用户活动(按省份)
此报告提供美国各州和哥伦比亚特区的用户活动统计信息。对于此报告,您必须将 filters
参数值设为 country==US
。
按城市统计的用户活动(<= 250 条结果)
注意:此报告要求您将 maxResults
参数设置为 250
或更低的整数值。与大多数其他报告不同,此类报告还要求您指定 sort
请求参数的值。
此报告会按城市提供用户活动统计信息。
播放详情
播放详情报告提供与以下观看属性相关的统计信息:
- 您观看的是直播视频还是点播视频?
- 观看者是否订阅了拥有该视频的频道?
- 观看的是 YouTube 上的什么产品?
注意:liveOrOnDemand 维度和过滤条件不能与 averageViewPercentage 指标结合使用。因此,以下各个小节均列出了两个报告。一个报告支持 liveOrOnDemand 维度(和过滤条件),而另一个报告支持 averageViewPercentage 指标。
用户活动(按订阅状态)
该报告会提供已订阅和未订阅的观看者的用户活动指标。统计信息可以按时间段(天或月)分组,还可以按国家/地区、大洲或次大陆进行过滤。
用户活动(按省份划分)状态
此报告提供美国各州或哥伦比亚特区订阅和退订观看者的用户活动指标。与上一个报告相比,此报告支持的指标更少。
带有可选时间维度的播放详情
时间维度 day 或 month – 对这些报告而言是可选的,因为无论您如何使用 startDate
和 endDate
请求参数,就要指定报告的日期范围。如果存在维度,则表示您希望按天、月等汇总报告中的数据。
此报告会提供特定时间间隔的播放详情统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
此报告会提供特定时间间隔的播放详情统计信息。它支持 averageViewPercentage 指标。
播放详细信息(按国家/地区)
此报告会提供各个国家/地区的播放详情统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
以下报告与上一份报告类似。它增加了对 averageViewPercentage 指标的支持,但不支持将 liveOrOnDemand 作为维度或过滤条件。
播放详细信息(按省份)
此报告提供美国各州和哥伦比亚特区的播放详情统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
以下报告与上一份报告类似。它增加了对 averageViewPercentage 指标的支持,但不支持将 liveOrOnDemand 作为维度或过滤条件。
播放位置
视频播放位置报告
此报告会提供与播放视频的类型或应用类型相关的统计信息。
播放位置详情 (<= 25 个结果)
注意:此报告要求您将 maxResults
参数设置为 25
或更低的整数值。与大多数其他报告不同,此类报告还要求您指定 sort
请求参数的值。
此报告可找出哪些嵌入式播放器为频道的视频带来了最多的观看次数或观看次数。
流量来源
流量来源
此报告会基于观看者找到您的视频内容的方式汇总观看次数统计信息。例如,它标识了源自 Google 搜索或相关视频链接的观看次数。
流量来源详细信息 (小于等于 25 个结果)
注意:此报告要求您将 maxResults
参数设置为 25
或更低的整数值。与大多数其他报告不同,此类报告还要求您指定 sort
请求参数的值。
此报告汇总的查看统计信息来自为频道内容带来了最多观看次数的引荐来源网址。引荐来源网址按流量来源类型分类,而 insighttrafficSourceDetail 维度的定义则标识了报告可用的流量来源。例如,如果您将 insighttrafficSourceType 过滤条件设置为 ADVERTISING
,则该报告会列出为频道内容带来了最多观看次数或观看时长的广告类型。
注意:只有特定流量来源支持此报告。例如,NO_LINK_EMBEDDED
流量来源就没有其他详细信息,因此不支持此报告。如需详细了解哪些流量来源支持此报告,请参阅insightTrafficSourceType定义。
设备类型和操作系统
设备类型
此报告会基于观看者找到您的视频内容的方式汇总观看次数统计信息。例如,它可确定移动设备或游戏机上的观看次数。
操作系统
此报告汇总了根据观看者的操作系统查看观看情况的统计信息。例如,它指定 Android 设备或 PlayStation 上的观看次数。
操作系统和设备类型
此报告根据观看者的操作系统和设备类型汇总了观看统计信息。例如,它可以确定在 Android 平板电脑或 Windows 桌面设备上的观看次数。
观看者受众特征
此报告会根据观看者的年龄段和性别汇总其观看统计信息。
深度互动和内容共享
此报告会提供统计信息,显示该频道的视频在不同社交平台上的分享频率。
观众黏度
此报告用于衡量视频留住观众的能力。elapsedVideoTimeRatio
维度衡量的是相应指标值对应的视频已播放时长。audienceWatchRatio
和 relativeRetentionPerformance
指标提供两种衡量指标,用于显示视频在吸引受众群体方面的表现。第一个是绝对值,而第二个显示的是视频相对于其他类似时长的 YouTube 视频的表现。
注意:观众黏度报告不支持为 video
过滤条件指定值列表(以英文逗号分隔)。该值必须指定一个视频 ID。
热门视频
注意:这些报告要求您将 maxResults
参数设置为 200
或更低的整数值。在 2013 年 1 月 1 日之前,系统仅提供前 10 个热门视频的数据。与大多数其他报告不同,这些报告还要求您指定 sort
请求参数的值。
可选地区过滤条件的热门视频(<= 200 个结果)
此报告会列出频道的热门视频。可对报告进行过滤,以便按国家/地区、大洲或次级大区列出热门视频。
各州的热门视频(<= 200 个结果)
此报告会列出该频道在特定美国或哥伦比亚特区的热门视频。请注意,此报告仅支持上述特定国家/地区报告中可用的部分指标。
已订阅或未订阅的观看者人数最多的视频(少于 200 个结果)
此报告会列出频道中订阅或退订的观看者的热门视频。可对报告进行过滤,以便按国家/地区、大洲或次级大区列出热门视频。上一份报告让您可以检索位于美国特定州且订阅者或未订阅的热门视频,但支持的报告指标少于此报告。
按 YouTube 产品划分的热门视频(<= 200 个结果)
此报告列出了频道中的热门视频,支持播放详情和地理位置过滤器。此报告与前一种报告类似,但支持的指标更少,并且支持 youtubeProduct 过滤条件。
包含播放详情过滤条件的热门视频(<= 200 个结果)
此报告列出了频道的热门视频,并按任意或全部播放详情维度过滤:liveOrOnDemand、subscribedStatus 和 youtubeProduct。与之前的报告不同,此报告支持 liveOrOnDemand 过滤条件,并且不支持 averageViewPercentage 指标。
播放列表报告
基本统计信息
此报告可提供有关用户与频道播放列表互动情况的统计信息。您可以过滤报告,以便仅返回特定播放列表或国家/地区的数据。
基于时间
此报告可提供有关用户与频道播放列表互动情况的统计信息。您可以过滤报告,以便仅返回特定播放列表或国家/地区的数据。
用户地理位置
播放列表活动(按国家/地区)
此报告可提供有关用户与频道播放列表互动情况的统计信息。您可以过滤报告,以便仅返回特定播放列表、一组播放列表或某个国家/地区的数据。
播放列表活动(按省份)
此报告提供美国各州和哥伦比亚特区的播放列表活动统计信息。对于此报告,您可以在 filters
参数值中添加 country==US
。
播放位置
此报告会提供与播放播放列表的网页类型或应用类型相关的统计信息。
播放位置详情 (<= 25 个结果)
注意:此报告要求您将 maxResults
参数设置为 25
或更低的整数值。与大多数其他报告不同,此类报告还要求您指定 sort
请求参数的值。
此报告会找出为频道播放列表生成的观看次数或观看时长最多的嵌入式视频播放器。
流量来源
此报告会根据观看者找到您的播放列表内容的方式汇总观看统计信息。例如,它标识了由 Google 搜索带来的观看次数。
流量来源详细信息 (小于等于 25 个结果)
注意:此报告要求您将 maxResults
参数设置为 25
或更低的整数值。与大多数其他报告不同,此类报告还要求您指定 sort
请求参数的值。
此报告会根据引荐者为频道播放列表生成最多观看次数的汇总统计信息。引荐来源网址按流量来源类型分类,而 insighttrafficSourceDetail 维度的定义则指明了可以生成此报告的流量来源。
例如,如果您将 insight TrafficSourceType 过滤条件设置为 ADVERTISING
,该报告就会列出为频道播放列表带来了最多观看次数或观看次数的广告类型。
注意:只有特定流量来源支持此报告。例如,NO_LINK_EMBEDDED
流量来源就没有其他详细信息,因此不支持此报告。如需详细了解哪些流量来源支持此报告,请参阅insightTrafficSourceType定义。
设备类型和操作系统
设备类型
此报告会根据观看者找到您的播放列表内容的方式汇总观看统计信息。例如,它可确定移动设备或游戏机上的观看次数。
操作系统
此报告汇总了根据观看者的操作系统查看观看情况的统计信息。例如,它可以确定在 Android 设备或 PlayStation 上发生的播放列表观看次数。
操作系统和设备类型
此报告根据观看者的操作系统和设备类型汇总了观看统计信息。例如,它可以确定在 Android 平板电脑或 Windows 桌面设备上发生的播放列表观看次数。
观看者受众特征
最常听的播放列表
注意:这些报告要求您将 maxResults
参数设置为 200
或更低的整数值。在 2013 年 1 月 1 日之前,系统仅提供前 10 个播放列表的数据。与大多数其他报告不同,这些报告还要求您指定 sort
请求参数的值。
此报告可根据指定的过滤条件和排序标准列出频道的热门播放列表。
注意:广告效果报告需要一个授权令牌,用来授予对 https://www.googleapis.com/auth/yt-analytics-monetary.readonly
范围的访问权限。
广告效果报告为视频播放期间投放的广告提供基于展示次数的指标。这些指标会计入每次广告展示,而每次视频播放可能会产生多次展示。
基于展示次数的广告效果指标如下:
此外,某些视频报告支持以下基于播放的广告效果指标。不过,这些指标不会包含在广告效果报告中。