注意: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 Analytics 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 指标的播放详情视频报告支持的维度、指标和过滤条件。
此表格包含两行维度、一行指标和三行过滤条件。对于维度和过滤条件,每行的值都可以在 API 请求中合并,前提是组合遵循表中的使用规则。例如,此报告的有效 dimensions
参数值包括:
dimensions=day
dimensions=day,liveOrOnDemand
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
不过,参数值 day,month
无效,因为它使用两个基于时间的维度,但请求可以使用 0 或 1。在这种情况下,参数值 subscribedStatus,youtubeProduct
实际上会返回一个报告,但指标不会按天、周、月等方式汇总(文档中单独记录了该报告)。
报告表格术语
表格使用以下术语来表示维度是必需维度还是可选维度:
- 这些术语表示必须提供一个值:
- 必需:您必须添加该值。
- 仅使用 1:您必须添加值组中的一个值。
- 使用 1 个或多个值:您可以添加组中的任意值或所有值,但必须至少包含一个值。
- 以下术语表示值是可选的:
- 可选:您可以选择添加值。
- 使用 0 或 1:您可以选择添加组中的一个值。
- 使用 0 或更大值:您可以选择添加组中的任意值或所有值。
重要提示:所有用于检索内容所有者视频报告的 API 请求都必须使用
视频维度、
频道维度、
群组维度或受支持的
claimedStatus 和
uploaderType 维度组合来过滤数据。(某些报告并不支持所有这些选项。)受支持的组合(在
uploaderType 维度的定义中也列出)包括:
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
视频报告
基本统计数据
基本统计信息(包括订阅人数)
此报告会提供与内容所有者的所有频道中的用户操作相关的统计信息。您可以对报告进行过滤,仅返回特定视频或国家/地区的数据。它还可用于仅检索已声明版权的内容的统计信息,包括由内容所有者和/或第三方上传的已声明版权的内容。
美国各州的基本统计信息
该报告会提供美国特定州或哥伦比亚特区的统计信息。请注意,此报告仅支持上述针对具体国家/地区的报告中提供的部分指标。
基于时间
不同时间段的活动
此报告会提供与用户在指定时间间隔内在内容所有者的所有频道中执行的操作相关的统计信息。您可以对报告进行过滤,仅返回特定视频或国家/地区的数据。
美国各州特定时间段内的用户活动
该报告会提供美国特定州或哥伦比亚特区的统计信息。请注意,此报告仅支持上述针对具体国家/地区的报告中提供的部分指标。
用户地理位置
按国家/地区细分的用户活动
此报告可按国家/地区提供内容所有者所有频道与用户活动相关的统计信息。您可以对报告进行过滤,仅返回特定视频或频道的数据。
用户活动(按省份)
此报告提供美国各州和哥伦比亚特区的用户活动统计信息。对于此报告,您必须将 filters
参数值设为 country==US
。
按城市细分的用户活动(<= 250 条结果)
注意:此报告要求您将 maxResults
参数设置为不超过 250
的整数值。与大多数其他报告不同,此报告还要求您为 sort
请求参数的值指定一个值。
此报告可按城市提供用户活动统计信息。
播放详情
播放详情报告提供与以下观看属性相关的统计信息:
- 观看的是直播视频还是点播视频?
- 观看者是否订阅了该视频所属的频道?
- 此次观看发生在哪个 YouTube 产品上?
从技术上讲,这些报告支持的播放详细信息维度都是可选的。如果您没有在请求中添加播放详情维度,则返回的报告实际上将类似于以下某一种报告:基本统计信息、基于时间的报告或用户地理位置报告。
注意:liveOrOnDemand 维度和过滤条件不能与 averageViewPercentage 指标结合使用。因此,以下每个小节都会列出两种报告。一个报告支持“liveOrOnDemand”维度(和过滤条件),而另一个报告支持 averageViewPercentage 指标。liveOrOnDemand
用户活动(按订阅状态)
此报告可针对已订阅和未订阅的观看者提供用户活动指标。您可以按时间段(天或月)对统计信息进行分组,还可以按国家/地区、大洲或subContinent对报告进行过滤。
各省份的用户活动(按订阅状态划分)
此报告提供了针对美国各州或哥伦比亚特区的已订阅和未订阅观看者的用户活动指标。与上一个报告相比,此报告支持的指标较少。
包含可选时间维度的播放详情
时间维度(天或月)对这些报告是可选的,因为无论如何,您都需要使用startDate
和endDate
请求参数来指定报告要涵盖的日期范围。此维度(如果存在)表示您希望按天、月等汇总报告中的数据。
此报告提供特定时间间隔内的播放详细统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
此报告提供特定时间间隔内的播放详细统计信息。
各个国家/地区的播放详情
该报告提供各个国家/地区的播放详情统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
下面的报告与前一个报告类似。它增加了对 averageViewPercentage 指标的支持,但不支持将 liveOrOnDemand 作为维度或过滤条件。
各省级行政区的播放详细信息
此报告提供美国各州和哥伦比亚特区的播放详细统计信息。它支持 liveOrOnDemand 维度(和过滤条件)。
下面的报告与前一个报告类似。它增加了对 averageViewPercentage 指标的支持,但不支持将 liveOrOnDemand 作为维度或过滤条件。
播放位置
视频播放位置报告
此报告提供与视频播放的网页或应用类型相关的统计信息。
播放位置详情(不超过 25 条结果)
注意:此报告要求您将 maxResults
参数设置为不超过 25
的整数值。与大多数其他报告不同,此报告还要求您为 sort
请求参数的值指定一个值。
此报告可找出为内容所有者的内容带来最多观看次数或观看时间的嵌入式视频播放器。检索此报告时,您必须将过滤条件“insightPlaybackLocationType
”设为“EMBEDDED
”。
流量来源
流量来源
此报告会根据观看者找到您视频内容的方式汇总观看统计信息。例如,标识源自 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 条结果)
此报告列出了订阅或未订阅观看者的热门视频。您可以过滤报告,按国家/地区、大洲或subContinent列出热门视频。上一个报告可让您检索美国特定州的订阅者或未订阅观看者的热门视频,但此报告支持的指标比此报告少。
按 YouTube 产品划分的热门视频(<= 200 个结果)
此报告列出了热门视频,并支持播放详细信息和地理位置过滤条件。此报告与前一种报告类似,但它支持的指标较少,并且增加了对 youtubeProduct 过滤条件的支持。
具有播放详情过滤条件的热门视频(不超过 200 条结果)
此报告会列出内容所有者的热门视频,并按一个或多个播放详情维度(liveOrOnDemand、subscribedStatus 和 youtubeProduct)进行过滤。该报告还支持按区域过滤。
播放列表报告
播放列表报告包含与频道所有者播放列表中的视频相关的用户活动相关的指标。这些报告有两个版本,对于每个可用的报告,以下部分包含每个版本的说明:
- 各部分中的建议标签页介绍了用于检索相应报告的首选 API 请求格式。推荐的报告支持一组经过扩展的指标,其中包括汇总视频指标和播放列表内指标。此请求格式不使用
isCurated
维度。
- 各部分中的使用
isCurated
标签页介绍了一种旧的 API 请求格式,该格式必须使用 isCurated
维度。这些报告仅支持播放列表内指标。请注意,isCurated
维度已针对所有报告弃用。下面的警告说明介绍了弃用时间表。
以下警告说明更详细地说明了这两个报告版本之间的变化。
汇总的视频指标
这些指标会提供用户活动和展示次数指标,这些指标会针对播放列表中的所有视频(同时也归拥有该播放列表的频道)提供汇总。汇总时不会计算其他频道所拥有的视频的指标。因此,如果某个频道创建的播放列表只包含其他频道所拥有的视频,那么这些播放列表的报告将不会提供这些指标的值。
如需查看 YouTube 支持的汇总视频指标列表,请参阅支持的播放列表指标部分。
播放列表内指标
这些指标反映了播放列表页面中的用户活动和互动度。这些指标包括播放列表中所有视频的观看次数(无论它们归哪个频道所有),但仅统计在播放列表环境中发生的观看次数。
支持的播放列表指标
基本统计数据
此报告提供关于用户与内容所有者频道播放列表中视频的互动情况的统计信息。此报告没有任何必需的维度。
基于时间
该报告会提供用户在指定时间间隔内与内容所有者频道的播放列表中的视频互动情况的相关统计信息。您可以对报告进行过滤,仅返回特定播放列表或频道的数据。
用户地理位置
该报告会提供特定国家/地区用户与频道播放列表中的视频的互动情况的相关统计信息。
此报告可按国家/地区提供播放列表统计信息。
播放列表活动(按省份)
此报告可提供美国各州和哥伦比亚特区的播放列表活动统计信息。对于此报告,请在 filters
参数值中添加 country==US
。
播放位置
该报告会提供与播放播放列表的网页或应用类型相关的统计信息。
播放位置详情(不超过 25 条结果)
注意:此报告要求您将 maxResults
参数设置为不超过 25
的整数值。与大多数其他报告不同,此报告还要求您为 sort
请求参数的值指定一个值。
此报告可找出为内容所有者的播放列表带来最多观看次数或观看时间的嵌入式视频播放器。
流量来源
此报告会根据观看者找到您播放列表内容的方式汇总观看统计信息。例如,标识源自 Google 搜索或频道页的观看次数。
流量来源详情(<= 25 条结果)
注意:此报告要求您将 maxResults
参数设置为不超过 25
的整数值。与大多数其他报告不同,此报告还要求您为 sort
请求参数的值指定一个值。
此报告依据为内容所有者的播放列表带来了最多观看次数的引荐来源网址,汇总了观看统计信息。引荐来源网址按流量来源类型分类,而 insightTrafficSourceDetail 维度的定义可标识可提供相关报告的流量来源。例如,如果您将 insightTrafficSourceType 过滤条件设置为 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
范围的访问权限。
广告效果报告可为视频播放期间投放的广告提供基于展示次数的指标。这些指标统计了每次广告展示,并且每次视频播放可产生多次展示。
基于展示次数的广告效果指标包括:
此外,一些视频报告还支持下列基于播放的广告效果指标。不过,广告效果报告中不包含这些指标。