YouTube Analytics API: Channel Reports

本页列出了频道所有者可以使用 YouTube 数据分析 API 检索的报告。频道报告会提供指定频道的用户活动指标，并衡量视频观看次数、评分和订阅人数等指标。

  • 视频报告会提供与频道视频相关的所有用户活动的统计信息。
  • 播放列表报告提供与播放列表中发生的视频观看次数密切相关的统计信息。

  • 广告效果报告包含与收入和广告效果相关的指标。这些指标使用 adType 维度，根据视频播放期间投放的广告类型对指标进行分组。“广告效果报告”部分介绍了该 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 支持的报告的表格中使用的格式和术语。下表列出了使用时间维度和averageViewPercentage指标的播放详情视频报告支持的维度、指标和过滤条件。

目录
尺寸：
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
使用 0 或 1 day、month
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 subscribedStatus、youtubeProduct

该表包含两行维度、一行指标和三行过滤器。对于维度和过滤条件，您可以在 API 请求中组合使用每行的值，前提是组合方式符合表格中的使用规则。例如，此报告的有效 dimensions 参数值包括：

  • dimensions=day
  • dimensions=day,subscribedStatus
  • dimensions=month,subscribedStatus,youtubeProduct
  • dimensions=month,youtubeProduct

但是，参数值 day,month 无效，因为它使用了两个基于时间的维度，而请求必须使用 0 或 1。

报告表格术语

表格使用以下术语来指明维度是必需的还是可选的：

  • 以下字词表示某个值是必填的：
    • 必填：您必须添加此值。
    • 使用 1：您必须从组中添加一个值。
    • 使用 1 个或更多值：您可以包含组中的任意值或所有值，但必须至少包含 1 个值。
  • 以下字词表示值为可选：
    • 可选：您可以选择添加该值。
    • 使用 0 或 1：您可以选择包含组中的某个值。
    • 使用 0 或更多：您可以选择包含组中的任意值或所有值。

视频报告

基本统计数据

基本用户活动统计信息

此报告提供与用户在频道上的操作相关的统计信息。您可以过滤报告，以便仅返回特定视频或国家/地区的数据。

目录
尺寸：
[无]
指标：
使用 1 或更多 views、redViews、comments、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks、subscribersGained、subscribersLost、estimatedRevenue*、estimatedAdRevenue*、grossRevenue*、estimatedRedPartnerRevenue*、monetizedPlaybacks*、playbackBasedCpm*、adImpressions*、cpm*
过滤器：
使用 0 或 1 country、continent、subContinent
使用 0 或 1 视频、组

美国各州的基本用户活动统计信息

此报告提供特定美国州或哥伦比亚特区的统计信息。请注意，此报告仅支持上述针对特定国家/地区的报告中提供的部分指标。

目录
尺寸：
[无]
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
必填 province
使用 0 或 1 视频、组

基于时间

特定时间段内按国家/地区划分的用户活动

此报告提供与频道上用户在特定时间段内的操作相关的统计信息。您可以过滤报告，以便仅返回特定视频或国家/地区的数据。

目录
尺寸：
使用 1 day、month
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、comments、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks、subscribersGained、subscribersLost、uniques、estimatedRevenue*、estimatedAdRevenue*、grossRevenue*、estimatedRedPartnerRevenue*、monetizedPlaybacks*、playbackBasedCpm*、adImpressions*、cpm*
过滤器：
使用 0 或 1 country、continent、subContinent
使用 0 或 1 视频、组

特定时间段内美国各州的用户活动

此报告提供与特定美国州或哥伦比亚特区用户活动相关的统计信息。请注意，此报告仅支持上述针对特定国家/地区的报告中提供的指标中的一部分。

目录
尺寸：
使用 1 day、month
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
必填 province
使用 0 或 1 视频、组

用户地理位置

按国家/地区划分的用户活动

此报告按国家/地区提供与频道用户活动相关的统计信息。您可以过滤报告，以便仅返回特定视频的数据。

目录
尺寸：
必填 country
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、comments、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks、subscribersGained、subscribersLost、estimatedRevenue*、estimatedAdRevenue*、grossRevenue*、estimatedRedPartnerRevenue*、monetizedPlaybacks*、playbackBasedCpm*、adImpressions*、cpm*
过滤器：
使用 0 或 1 continent、subContinent
使用 0 或 1 视频、组

用户活动（按省份）

此报告提供美国各州和哥伦比亚特区的用户活动统计信息。 对于此报告，您必须将 filters 参数值设置为 country==US。

目录
尺寸：
必填 province
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
必填 country==US
使用 0 或 1 视频、组

按城市统计的用户活动（结果不超过 250 条）

注意：若要生成此报告，您需要将 maxResults 参数设置为不超过 250 的整数值。与大多数其他报告不同，此报告还要求您为 sort 请求参数指定一个值。

此报告按城市提供用户活动统计信息。

目录
尺寸：
必填 city
使用 0 或更大的值 creatorContentType、country、province、subscribedStatus

注意：如果您添加了省/直辖市/自治区维度，则还必须使用 country==US 过滤条件。
使用 0 或 1 day、month
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
排序选项： -views
-estimatedMinutesWatched

用户活动（按 DMA）

此报告按指定的市场区域 (DMA) 提供用户活动统计信息。对于此报告，您必须将 filters 参数值设置为 country==US，或者过滤到特定省级行政区（美国州）。

目录
尺寸：
必填 dma
使用 0 或 1 day
month
creatorContentType
subscribedStatus
指标：
使用 1 或更多 次观看
estimatedMinutesWatched
averageViewDuration
averageViewPercentage
过滤器：
使用 0 或 1 country==US
province
使用 0 或 1 视频
组
排序选项： -views
-estimatedMinutesWatched

播放详情

播放详细报告会提供与以下观看属性相关的统计信息：

  • 观看的是直播视频还是点播视频？
  • 观看者是否订阅了视频所属的频道？
  • 观看发生在哪款 YouTube 产品上？

注意：liveOrOnDemand 维度和过滤条件不能与 averageViewPercentage 指标结合使用。因此，以下各小节都列出了两个报告。一个报告支持“liveOrOnDemand”维度（和过滤条件），另一个报告支持“averageViewPercentage”指标。liveOrOnDemandaverageViewPercentage

按订阅状态划分的用户活动情况

此报告会提供订阅者和非订阅者用户的活动指标。统计数据可按时间段（天或月）进行分组，您还可以按国家/地区、大洲或subContinent过滤报告。

目录
尺寸：
使用 0 或更大的值 creatorContentType、subscribedStatus
使用 0 或 1 day、month
指标：
使用 1 或更多 views、redViews、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
使用 0 或 1 country、continent、subContinent
使用 0 或 1 视频、组
可选 subscribedStatus

按省份划分的用户活动情况（按订阅状态）

此报告会针对美国各州或哥伦比亚特区的订阅和未订阅观看者提供用户活动指标。与之前的报告相比，此报告支持的指标更少。

目录
尺寸：
使用 0 或更大的值 creatorContentType、subscribedStatus
使用 0 或 1 day、month
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
使用 0 或 1 视频、组
使用 0 或更大的值 province、subscribedStatus

包含可选时间维度的播放详情

时间维度（天或月）对于这些报告而言是可选的，因为无论如何，您都需要使用 startDate 和 endDate 请求参数来指定报告将涵盖的日期范围。如果存在，该维度表示您希望按天、月等汇总报告中的数据。

播放详情，包括可选的时间维度和 liveOrOnDemand 统计信息

此报告会提供特定时间段的播放详细统计信息。它支持 liveOrOnDemand 维度（和过滤条件）。

目录
尺寸：
使用 0 或更大的值 creatorContentType、liveOrOnDemand、subscribedStatus、youtubeProduct
使用 0 或 1 day、month
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus、youtubeProduct
播放详情，包含可选的时间维度和averageViewPercentage指标

此报告会提供特定时间段的播放详细统计信息。它支持 averageViewPercentage 指标。

目录
尺寸：
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
使用 0 或 1 day、month
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 subscribedStatus、youtubeProduct

按国家/地区划分的播放详情

按国家/地区显示的播放详情，以及 liveOrOnDemand 统计信息

此报告按国家/地区提供播放详细统计信息。它支持 liveOrOnDemand 维度（和过滤条件）。

目录
尺寸：
必填 country
使用 0 或更大的值 creatorContentType、liveOrOnDemand、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration
过滤器：
使用 0 或 1 continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus、youtubeProduct
按国家/地区显示的播放详情，其中包含averageViewPercentage 指标

以下报告与上一个报告类似。它支持 averageViewPercentage 指标，但不支持将 liveOrOnDemand 用作维度或过滤条件。

目录
尺寸：
必填 country
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 0 或 1 continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 subscribedStatus、youtubeProduct

按省级行政区划的播放详情

按省级别显示的播放详情，以及 liveOrOnDemand 统计信息

此报告提供美国各州和哥伦比亚特区的播放详细统计信息。它支持 liveOrOnDemand 维度（和过滤条件）。

目录
尺寸：
必填 province
使用 0 或更大的值 creatorContentType、liveOrOnDemand、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration
过滤器：
必填 country==US
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus、youtubeProduct
按省级别显示的播放详情，其中包含averageViewPercentage指标

以下报告与上一个报告类似。它支持 averageViewPercentage 指标，但不支持将 liveOrOnDemand 用作维度或过滤条件。

目录
尺寸：
必填 province
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
必填 country==US
使用 0 或 1 视频、组
使用 0 或更大的值 subscribedStatus、youtubeProduct

播放位置

视频播放位置报告

此报告提供与视频播放发生的网页或应用类型相关的统计信息。

目录
尺寸：
必填 insightPlaybackLocationType
使用 0 或更大的值 creatorContentType、day、liveOrOnDemand、subscribedStatus
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus

播放位置详情（不超过 25 条结果）

注意：若要生成此报告，您需要将 maxResults 参数设置为不超过 25 的整数值。与大多数其他报告不同，此报告还要求您为 sort 请求参数指定一个值。

此报告会指出为频道视频带来最多观看次数或观看时长的嵌入式视频播放器。

目录
尺寸：
必填 insightPlaybackLocationDetail
可选 creatorContentType
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
必填 insightPlaybackLocationType==EMBEDDED
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus
排序选项： -views
-estimatedMinutesWatched

流量来源

流量来源

此报告会根据观看者观看您的视频内容的方式汇总观看统计数据。例如，它可以识别是通过 Google 搜索还是通过指向相关视频的链接获得的观看次数。

注意：如果查询的视频数量 x 日期范围内的天数的乘积超过 5 万，此报告会返回错误。例如，用于检索 500 个视频 ID 的数据的查询最多可以请求 100 天内的数据。如需减少请求返回的行数，请将查询拆分为多个查询，指定更少的视频或设置更短的日期范围。

目录
尺寸：
必填 insightTrafficSourceType
使用 0 或更大的值 creatorContentType、day、liveOrOnDemand、subscribedStatus
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus

流量来源详情 （不超过 25 条结果）

注意：若要生成此报告，您需要将 maxResults 参数设置为不超过 25 的整数值。与大多数其他报告不同，此报告还要求您为 sort 请求参数指定一个值。

此报告会根据为频道内容带来最多观看次数的引荐来源汇总观看统计信息。引荐来源会按流量来源类型进行分类，insightTrafficSourceDetail 维度的定义可用于确定报告适用的流量来源。例如，如果您将 insightTrafficSourceType 过滤条件设置为 ADVERTISING，报告中将列出为频道内容带来最多观看次数或观看时长的广告类型。

目录
尺寸：
必填 insightTrafficSourceDetail
可选 creatorContentType
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
必填 insightTrafficSourceType（请参阅下表中的备注）
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus
排序选项： -views
-estimatedMinutesWatched

注意：只有特定的流量来源支持此报告。VIDEO_REMIXES、NOTIFICATION、END_SCREEN、CAMPAIGN_CARD、VIDEO_REMIXES 和 NO_LINK_EMBEDDED 流量来源是其中一些不受支持的来源。

设备类型和操作系统

设备类型

此报告会根据观看者观看您的视频内容的方式汇总观看统计数据。例如，它可识别在移动设备或游戏机上发生的观看次数。

目录
尺寸：
必填 deviceType
使用 0 或更大的值 creatorContentType、day、liveOrOnDemand、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

操作系统

此报告会根据观看者的操作系统汇总观看统计信息。例如，它可识别在 Android 设备或 PlayStation 上发生的观看次数。

目录
尺寸：
必填 operatingSystem
使用 0 或更大的值 creatorContentType、day、liveOrOnDemand、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 deviceType、liveOrOnDemand、subscribedStatus、youtubeProduct

操作系统和设备类型

此报告会根据观看者的操作系统和设备类型汇总观看统计信息。例如，它可识别在 Android 平板电脑或 Windows 桌面设备上发生的观看次数。

目录
尺寸：
必填 deviceType、operatingSystem
使用 0 或更大的值 creatorContentType、day、liveOrOnDemand、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus、youtubeProduct

观看者受众特征

此报告会根据观看者的年龄段和性别汇总观看统计信息。

目录
尺寸：
使用 1 或更多 ageGroup、gender
使用 0 或更大的值 creatorContentType、liveOrOnDemand、subscribedStatus
指标：
使用 1 或更多 viewerPercentage
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或 1 视频、组
使用 0 或更大的值 liveOrOnDemand、subscribedStatus
注意：此报告中的viewerPercentage值不会针对播放详情维度（subscribedStatus、liveOrOnDemand 或 youtubeProduct）的不同值或值组合进行标准化处理。

例如，使用 subscribedStatus 维度的报告会针对已订阅的观看返回的viewerPercentage数据和未订阅的观看返回的viewerPercentage数据总和为 100%。（报告中所有viewerPercentage字段的总值为 200%。）

您可以使用过滤条件，确保报告仅包含播放详情维度中一个值（或值组合）的viewerPercentage数据。

互动和内容分享

此报告提供统计信息，显示频道视频在不同社交平台上的分享频率。

目录
尺寸：
必填 sharingService
使用 0 或更大的值 creatorContentType、subscribedStatus
指标：
使用 1 或更多 share
过滤器：
使用 0 或 1 country、continent、subContinent
使用 0 或 1 视频、组
可选 subscribedStatus

观众黏度

此报告可衡量视频的观众黏度，还会显示视频的特定部分被观看的频率。elapsedVideoTimeRatio 维度用于衡量相应指标值所对应的视频播放时长。这些指标可分为两类：

  • 观众黏度

    这些指标显示了视频对观众的吸引力。

    • audienceWatchRatio 是一个比率，用于比较视频的某个片段的观看次数与视频的总观看次数。
    • relativeRetentionPerformance 显示视频在播放期间吸引观看者继续观看的能力，相对于时长相近的其他 YouTube 视频而言。

  • 精细的观看统计信息

    这些指标可提供有关视频中特定部分的观看频率的信息。

注意：此报告不支持为 video 过滤条件指定以英文逗号分隔的值列表；值必须指定单个视频 ID。

目录
尺寸：
必填 elapsedVideoTimeRatio
指标：
使用 1 或更多 audienceWatchRatio
relativeRetentionPerformance
startedWatching
stoppedWatching
totalSegmentImpressions
过滤器：
必填 video
使用 0 或更大的值 audienceType
subscribedStatus
youtubeProduct

同时观看人数（适用于直播）

此报告会显示单个直播视频在给定位置的同时观看人数。 过滤条件指定了视频。位置维度通常表示一分钟。

目录
尺寸：
使用 0 或 1 livestreamPosition
指标：
使用 1 或更多 averageConcurrentViewers
peakConcurrentViewers
过滤器：
必填 video

热门视频

注意：若要生成这些报告，您需要将 maxResults 参数设置为不超过 200 的整数值。系统仅提供 2013 年 1 月 1 日之前前 10 个视频的数据。与大多数其他报告不同，这些报告还要求您为 sort 请求参数指定一个值。

热门视频（可选地区过滤条件）（不超过 200 条结果）

此报告会列出频道的热门视频。您可以过滤此报告，按国家/地区、洲或subContinent列出热门视频。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、comments、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks、subscribersGained、subscribersLost、estimatedRevenue*、estimatedAdRevenue*、grossRevenue*、estimatedRedPartnerRevenue*、monetizedPlaybacks*、playbackBasedCpm*、adImpressions*、cpm*
过滤器：
使用 0 或 1 country、continent、subContinent
排序选项： -views
-redViews
-estimatedRevenue
-estimatedRedPartnerRevenue
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-subscribersGained
-subscribersLost

按州划分的热门视频（不超过 200 条结果）

此报告会列出频道在特定美国州或哥伦比亚特区最热门的视频。请注意，此报告仅支持上述针对特定国家/地区的报告中提供的指标中的一部分。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
必填 province
可选 subscribedStatus
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

订阅者或非订阅者最喜欢的视频（结果不超过 200 个）

此报告会列出频道中最受订阅者或未订阅者欢迎的视频。您可以过滤此报告，按国家/地区、大洲或subContinent列出热门视频。通过上一个报告，您可以查看特定美国州订阅者或非订阅者最喜欢的视频，但它支持的指标数量比此报告少。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、likes、dislikes、videosAddedToPlaylists、videosRemovedFromPlaylists、shares、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage、annotationClickThroughRate、annotationCloseRate、annotationImpressions、annotationClickableImpressions、annotationClosableImpressions、annotationClicks、annotationCloses、cardClickRate、cardTeaserClickRate、cardImpressions、cardTeaserImpressions、cardClicks、cardTeaserClicks
过滤器：
可选 subscribedStatus
使用 0 或 1 country、continent、subContinent
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

按 YouTube 产品显示热门视频（不超过 200 条结果）

此报告会列出频道中的热门视频，并支持播放详情和地理位置过滤条件。此报告与上一个报告类似，但支持的指标更少，并且新增了对 youtubeProduct 过滤条件的支持。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或更大的值 subscribedStatus、youtubeProduct
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

使用播放详情过滤条件的热门视频（不超过 200 条结果）

此报告会列出频道的热门视频，并按以下任一或全部播放详情维度进行过滤：liveOrOnDemand、subscribedStatus 和 youtubeProduct。与上一个报告不同，此报告支持 liveOrOnDemand 过滤条件，但不支持 averageViewPercentage 指标。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration
过滤器：
使用 0 或 1 country、province、continent、subContinent
使用 0 或更大的值 liveOrOnDemand、subscribedStatus、youtubeProduct
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

播放列表报告

播放列表报告包含与频道所有者播放列表中的视频相关的用户活动指标。这些报告有两个版本，以下部分介绍了每个可用报告的每个版本：

  • 每个部分中的建议标签页介绍了用于检索相应报告的首选 API 请求格式。推荐的报告支持一组更广泛的指标，包括汇总视频指标和播放列表内指标。此请求格式不使用 isCurated 维度。
  • 每个部分中的 Using isCurated 标签页介绍了需要 isCurated 维度的旧版 API 请求格式。这些报告仅支持播放列表内指标。请注意，isCurated 维度已在所有报告中废弃。以下警告备注介绍了弃用时间表。

以下警告说明详细介绍了这两种报告版本之间的变化。

汇总视频指标

这些指标提供的用户活动和展示次数指标是针对播放列表中所有同时归播放列表所属频道所有的视频汇总得出的。系统不会在汇总时计算其他频道所拥有的视频的指标。因此，如果某个频道创建的播放列表仅包含其他频道拥有的视频，则这些播放列表的报告不会提供这些指标的值。

如需查看 YouTube 支持的汇总视频指标列表，请参阅支持的播放列表指标部分。

播放列表内指标

这些指标反映了播放列表页面中的用户活动和互动情况。这些指标包括播放列表中所有视频的观看次数，无论这些视频归哪个频道所有，但仅统计在播放列表情境中发生的观看次数。

支持的播放列表指标

基本统计数据

此报告提供与用户与频道播放列表中的视频互动相关的统计信息。您可以过滤报告，以便仅返回特定播放列表的数据。

使用 isCurated
目录
尺寸：
[无]
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、playlistStarts、viewsPerPlaylistStart、averageTimeInPlaylist
过滤器：
必填 isCurated==1
使用 0 或 1 播放列表、分组
使用 0 或 1 country、province、continent、subContinent
使用 0 或更大的值 subscribedStatus、youtubeProduct

基于时间

此报告提供与用户与频道播放列表中的视频互动相关的统计信息。您可以过滤报告，以便仅返回特定播放列表的数据。

用户地理位置

按国家/地区划分的播放列表活动

此报告提供与特定国家/地区用户与频道播放列表中的视频互动相关的统计信息。

播放列表活动（按省级行政区）

此报告提供美国各州和哥伦比亚特区的播放列表活动统计信息。 对于此报告，您必须过滤结果，以便仅返回美国的数据。

播放位置

此报告提供与播放列表视频的播放位置（网页或应用）类型相关的统计信息。

播放位置详情（不超过 25 条结果）

注意：若要生成此报告，您需要将 maxResults 参数设置为不超过 25 的整数值。与大多数其他报告不同，此报告还要求您为 sort 请求参数指定一个值。

此报告会指出为频道播放列表中的视频带来最多观看次数或观看时长的嵌入式视频播放器。

流量来源

此报告会根据观看者观看播放列表内容的方式汇总观看统计信息。 例如，它可以识别通过 Google 搜索带来的观看次数。

流量来源详情 （不超过 25 条结果）

注意：若要生成此报告，您需要将 maxResults 参数设置为不超过 25 的整数值。与大多数其他报告不同，此报告还要求您为 sort 请求参数指定一个值。

此报告会根据为频道播放列表中的视频带来最多观看次数的引荐来源汇总观看统计信息。引荐来源会按流量来源类型进行分类，insightTrafficSourceDetail 维度的定义会指明报告适用于哪些流量来源。

例如，如果您将 insightTrafficSourceType 过滤条件设置为 ADVERTISING，报告将列出为频道播放列表带来最多观看次数或观看时长的广告类型。

注意：此报告仅适用于特定的流量来源。VIDEO_REMIXES、NOTIFICATION、END_SCREEN、CAMPAIGN_CARD、VIDEO_REMIXES 和 NO_LINK_EMBEDDED 流量来源是其中一些不受支持的来源。

设备类型和操作系统

设备类型

此报告会根据观看者观看您播放列表中视频的方式汇总观看统计数据。例如，它可识别在移动设备或游戏机上发生的观看次数。

操作系统

此报告会根据观看者的操作系统汇总观看统计信息。例如，它可识别在 Android 设备或 PlayStation 上发生的观看次数。

操作系统和设备类型

此报告会根据观看者的操作系统和设备类型汇总观看统计信息。 例如，它可以识别 Android 平板电脑或 Windows 桌面设备上的观看次数。

观看者受众特征

使用 isCurated
目录
尺寸：
使用 1 或更多 ageGroup、gender
使用 0 或更大的值 subscribedStatus
指标：
必填 viewerPercentage
过滤器：
必填 isCurated==1
使用 0 或 1 播放列表、分组
使用 0 或 1 country、province、continent、subContinent
可选 subscribedStatus
注意：此报告中的viewerPercentage值不会针对subscribedStatus播放详情维度的不同值进行标准化。

例如，使用subscribedStatus维度的报告会针对订阅的观看返回的viewerPercentage数据和针对未订阅的观看返回的viewerPercentage数据总和为 100%。（报告中所有viewerPercentage字段的总值为 200%。）

您可以使用过滤条件来确保报告仅包含subscribedStatus 维度的一个值的viewerPercentage数据。

表现最好的播放列表

注意：若要生成这些报告，您需要将 maxResults 参数设置为不超过 200 的整数值。系统仅提供 2013 年 1 月 1 日之前的前 10 个播放列表的数据。与大多数其他报告不同，这些报告还要求您为 sort 请求参数指定一个值。

此报告会根据指定的过滤条件和排序条件，列出频道的热门播放列表。

使用 isCurated
目录
尺寸：
必填 播放列表
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、playlistStarts、viewsPerPlaylistStart、averageTimeInPlaylist
过滤器：
必填 isCurated==1
使用 0 或 1 country、province、continent、subContinent
使用 0 或更大的值 playlist、subscribedStatus、youtubeProduct
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-playlistStarts

会员报告

取消会员资格

此报告提供统计信息，显示用户取消频道会员资格的原因。

目录
尺寸：
使用 0 或 1 membershipsCancellationSurveyReason
指标：
必填 membershipsCancellationSurveyResponses

广告效果报告

注意：广告效果报告需要授权令牌，以便授予对 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围的访问权限。

广告效果报告会针对视频播放期间投放的广告提供基于展示次数的指标。这些指标会统计每次广告展示，而每次视频播放可能会产生多次展示。

基于展示次数的广告效果指标包括：

此外，某些视频报告支持以下基于播放的广告效果指标。不过，广告效果报告中不包含这些指标。

按广告类型划分的广告效果

目录
尺寸：
必填 adType
可选 day
指标：
使用 1 或更多 grossRevenue、adImpressions、cpm
过滤器：
使用 0 或 1 视频、组
使用 0 或 1 country、continent、subContinent