YouTube Analytics API: Content Owner Reports

注意： Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.

本页列出了内容所有者可以使用 YouTube Analytics API 检索的报告。内容所有者报告包含与指定 YouTube 内容所有者相关联的频道的各种指标。指标是指用户活动、广告效果或预估收入的各项衡量指标。

  • 视频报告包含内容所有者频道中视频的用户活动、广告效果和预估收入指标。

  • 播放列表报告提供的统计信息与在播放列表情境中发生的视频观看次数密切相关。播放列表报告与视频报告使用许多相同的维度和过滤条件。

  • 广告效果报告包含与收入和广告效果相关的指标。它们使用 adType 维度，根据视频播放期间投放的广告类型对指标进行分组。“广告效果报告”部分介绍了该 API 支持的两种广告效果指标。

检索报告

如需检索内容所有者报告，请调用 API 的 reports.query 方法，并将 API 请求中的 ids 参数值设置为 contentOwner==OWNER_NAME，其中 OWNER_NAME 指定内容所有者的 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 范围的访问权限。

过滤条件

用于检索内容所有者报告的所有 API 请求都必须使用 video 维度、channel 维度、isCurated 维度或 claimedStatus 维度和 uploaderType 维度的受支持组合来过滤数据。（uploaderType 维度的定义中列出了受支持的组合。）

介绍受支持报告的表格会指明可用于任何给定报告的过滤条件。在说明中，括号中的过滤条件为可选项。例如，如果某个报告将 video(,country) 列为过滤选项，则可以过滤该报告，使其仅包含特定视频的数据，或者仅包含特定国家/地区的特定视频的数据。

该 API 还支持为 video、playlist 和 channel 过滤条件指定多个值。如果您为其中一个过滤条件指定了多个值，还可以将该过滤条件添加到为请求指定的维度列表中。即使过滤条件未列为特定报告的受支持维度，也是如此。

如需全面了解如何过滤出特定值或一组值的 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 或更多：您可以选择包含组中的任意值或所有值。
重要提示：用于检索内容所有者视频报告的所有 API 请求都必须使用视频维度、频道维度、组维度或claimedStatus 和 uploaderType 维度的支持组合来过滤数据。（某些报告不支持所有这些选项。）支持的组合（也列在 uploaderType 维度的定义中）如下：
  • uploaderType==self
  • claimedStatus==claimed
  • claimedStatus==claimed;uploaderType==self
  • claimedStatus==claimed;uploaderType==thirdParty

视频报告

基本统计数据

基本统计信息（包括订阅人数）

此报告提供与内容所有者所有频道上的用户操作相关的统计信息。您可以过滤报告，以便仅返回特定视频或国家/地区的数据。您还可以使用此 API 仅检索收到版权主张的内容的统计信息，包括内容所有者或第三方（或两者）上传的收到版权主张的内容。

目录
尺寸：
[无]
指标：
使用 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*
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、continent、subContinent

美国各州的基本统计信息

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

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

基于时间

特定时间段内的活动

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

目录
尺寸：
使用 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*
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、continent、subContinent

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

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

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

用户地理位置

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

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

目录
尺寸：
必填 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*
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 continent、subContinent

用户活动（按省份）

此报告提供美国各州和哥伦比亚特区的用户活动统计信息。对于此报告，您必须将 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
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
必填 country==US

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

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

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

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

注意：如果您添加了省/直辖市/自治区维度，则还必须使用 country==US 过滤条件。
使用 0 或 1 day、month
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、province、continent、subContinent
排序选项： -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
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、continent、subContinent
可选 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
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
必填 province
可选 subscribedStatus

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

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

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

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

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

此报告会提供特定时间段的播放详细统计信息。

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

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

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

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

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

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

目录
尺寸：
可选 country
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 continent、subContinent
使用 0 或更大的值 subscribedStatus、youtubeProduct

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

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

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

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

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

目录
尺寸：
可选 province
使用 0 或更大的值 creatorContentType、subscribedStatus、youtubeProduct
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration、averageViewPercentage
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
必填 country==US
使用 0 或更大的值 subscribedStatus、youtubeProduct

播放位置

视频播放位置报告

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

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

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

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

此报告会标识为内容所有者的内容带来了最多观看次数或观看时长的嵌入式视频播放器。检索此报告时，您必须将 insightPlaybackLocationType 过滤条件设置为 EMBEDDED。

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

流量来源

流量来源

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

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

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

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

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

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

目录
尺寸：
必填 insightTrafficSourceDetail
可选 creatorContentType
指标：
使用 1 或更多 观看次数、estimatedMinutesWatched
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
必填 insightTrafficSourceType（请参阅下表中的备注）
使用 0 或 1 country、province、continent、subContinent
使用 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
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、province、continent、subContinent
使用 0 或更大的值 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

操作系统

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

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

操作系统和设备类型

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

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

观看者受众特征

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

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

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

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

互动和内容分享

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

目录
尺寸：
必填 sharingService
可选 creatorContentType、subscribedStatus
指标：
使用 1 或更多 分享
过滤器：
使用 1 视频、频道、群组，或 uploaderType 和 claimedStatus 的支持组合
使用 0 或 1 country、continent、subContinent
可选 subscribedStatus

观众黏度

此报告衡量的是视频在吸引受众群体方面的吸引力。elapsedVideoTimeRatio 维度用于衡量相应指标值所对应的视频播放时长。audienceWatchRatio 和 relativeRetentionPerformance 指标提供了两个衡量标准，用于衡量视频对观众的吸引力。第一个值是绝对值，而第二个值则显示该视频相对于时长相近的其他 YouTube 视频的表现。

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

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

热门视频

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

按国家/地区、大洲或次大陆查看热门视频（不超过 200 条结果）

此报告会根据指定的过滤条件和排序条件，列出内容所有者的热门视频。

目录
尺寸：
必填 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*
过滤器：
使用 1 channel，或 uploaderType 和 claimedStatus 的支持组合
使用 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
过滤器：
使用 1 channel，或 uploaderType 和 claimedStatus 的支持组合
必填 province
排序选项： -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
过滤器：
使用 1 channel，或 uploaderType 和 claimedStatus 的支持组合
可选 subscribedStatus
使用 0 或 1 country、continent、subContinent
排序选项： -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

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

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

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

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

此报告会列出内容所有者的热门视频，并按一个或多个播放详情维度进行过滤：liveOrOnDemand、subscribedStatus 和 youtubeProduct。该报告还支持按地区进行过滤。

目录
尺寸：
必填 video
可选 creatorContentType
指标：
使用 1 或更多 views、redViews、estimatedMinutesWatched、estimatedRedMinutesWatched、averageViewDuration
过滤器：
使用 1 channel，或 uploaderType 和 claimedStatus 的支持组合
使用 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

基于时间

此报告提供与内容所有者频道在特定时间段内与播放列表中视频的互动情况相关的统计信息。您可以过滤报告，使其仅返回特定播放列表或频道的数据。

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

用户地理位置

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

此报告按国家/地区提供播放列表统计信息。

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

此报告提供美国各州和哥伦比亚特区的播放列表活动统计信息。对于此报告，您需要在 filters 参数值中添加 country==US。

播放位置

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

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

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

此报告会找出为内容所有者的播放列表带来最多观看次数或观看时长的嵌入式视频播放器。

推荐
目录
尺寸：
必填 insightPlaybackLocationDetail
指标：
使用 1 或更多 views、estimatedMinutesWatched、averageViewDuration、averageTimeInPlaylist、playlistAverageViewDuration、playlistEstimatedMinutesWatched、playlistStarts、playlistViews、viewsPerPlaylistStart
过滤器：
必填 insightPlaybackLocationType==EMBEDDED
使用 0 或 1* 播放列表、组

注意：如果报告中请求了观看次数、estimatedMinutesWatched或averageViewDuration指标，则必须指定其中一个过滤条件。
可选 channel
排序选项： -playlistViews
-playlistEstimatedMinutesWatched
-playlistStarts

流量来源

此报告会根据观看者访问播放列表内容的方式汇总观看统计信息。例如，它可以识别是通过 Google 搜索还是通过频道页获得的观看次数。

推荐
目录
尺寸：
必填 insightTrafficSourceType
指标：
使用 1 或更多 views、estimatedMinutesWatched、averageViewDuration、averageTimeInPlaylist、playlistAverageViewDuration、playlistEstimatedMinutesWatched、playlistSaves、playlistStarts、playlistViews、viewsPerPlaylistStart
过滤器：
使用 0 或 1* 播放列表、组

注意：如果报告中请求了观看次数、estimatedMinutesWatched或averageViewDuration指标，则必须指定其中一个过滤条件。
可选 channel

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

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

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

推荐
目录
尺寸：
必填 insightTrafficSourceDetail
指标：
使用 1 或更多 views、estimatedMinutesWatched、averageViewDuration、averageTimeInPlaylist、playlistAverageViewDuration、playlistEstimatedMinutesWatched、playlistSaves、playlistStarts、playlistViews、viewsPerPlaylistStart
过滤器：
必填 insightTrafficSourceType
使用 0 或 1* 播放列表、组

注意：如果报告中请求了观看次数、estimatedMinutesWatched或averageViewDuration指标，则必须指定其中一个过滤条件。
可选 channel
排序选项： -playlistViews
-playlistEstimatedMinutesWatched
-playlistStarts

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

设备类型和操作系统

播放列表的设备类型

此报告会根据观看者观看播放列表内容时所用的设备类型汇总观看统计信息。例如，它可识别在移动设备或游戏机上发生的观看次数。

播放列表的操作系统

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

播放列表的操作系统和设备类型

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

观看者受众特征

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

注意：此报告中的viewerPercentage值不会针对播放详情维度（subscribedStatus 和 youtubeProduct）的不同值或值组合进行标准化处理。

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

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

表现最好的播放列表

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

此报告会根据指定的过滤条件和排序条件，列出内容所有者的热门播放列表。

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

广告效果报告

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

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

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

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

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

目录
尺寸：
必填 adType
可选 day
指标：
使用 1 或更多 grossRevenue、adImpressions、cpm
过滤器：
使用 1 video、group，或 uploaderType 和 claimedStatus 的受支持组合
使用 0 或 1 country、continent、subContinent