本文档定义了您可以使用 YouTube Analytics API 检索的指标。此 API 支持实时查询,可生成自定义 YouTube 数据分析报告。
指标是对用户活动、广告效果或估算收入的单独衡量。用户活动指标包括视频观看次数和评分(顶和踩)等。
核心指标
虽然 YouTube Analytics API 受《服务条款》中定义的弃用政策约束,但非核心指标(和非核心维度)不受该政策约束。在本页面的定义中,任何属于核心指标的指标都会明确标识为核心指标。
下表列出了该 API 的核心指标。
annotationClickThroughRateannotationCloseRateaverageViewDurationcommentsdislikesengagedViewsestimatedMinutesWatchedestimatedRevenuelikessharessubscribersGainedsubscribersLostviewerPercentageviews
如需了解详情,请参阅受弃用政策约束的 YouTube API 列表。
查看指标
- engagedViews(核心指标) 频道视频在第一帧之后被观看的次数,或用户点击/点按播放的次数。
- 浏览量(核心指标)
- 此指标在不同类型的报告中代表不同的数字。此指标包含同看次数,即多人在电视屏幕上一起观看的次数。
This is a core metric and is subject to the Deprecation Policy.
- playlistViews
- 此指标在播放列表指标部分中定义。
- redViews
- YouTube Premium(以前称为“YouTube Red”)会员观看视频的次数。
- viewerPercentage(核心指标)
- 观看视频或播放列表时已登录的观看者所占的百分比。This is a core metric and is subject to the Deprecation Policy.
观看时长指标
- estimatedMinutesWatched(核心指标)
- 用户观看指定频道、内容所有者、视频或播放列表中的视频的时长(以分钟为单位)。此指标包含同看次数,即多人在电视屏幕上一起观看的次数。This is a core metric and is subject to the Deprecation Policy.
- estimatedRedMinutesWatched
- YouTube Premium(以前称为“YouTube Red”)会员观看视频的时长(以分钟为单位)。
- averageViewDuration(核心指标)
- 视频播放的平均时长(以秒为单位)。自 2021 年 12 月 13 日起,此指标不包括循环播放的剪辑流量。在播放列表报告中,该指标表示在播放列表中发生的视频播放的平均时长(以秒为单位)。This is a core metric and is subject to the Deprecation Policy.
- averageViewPercentage
- 视频播放期间的平均观看百分比。自 2021 年 12 月 13 日起,此指标不包括循环播放的剪辑流量。
互动指标
- 评论数(核心指标)
- 用户评论视频的次数。如需了解详情,请访问 YouTube 帮助中心。This is a core metric and is subject to the Deprecation Policy.
- likes(核心指标)
- 用户通过给出好评表示喜欢某个视频的次数。This is a core metric and is subject to the Deprecation Policy.
- dislikes(核心指标)
- 用户通过给出差评表示不喜欢某个视频的次数。This is a core metric and is subject to the Deprecation Policy.
- 用户通过
Share按钮分享视频的次数。如需了解详情,请访问 YouTube 帮助中心。This is a core metric and is subject to the Deprecation Policy. - subscribersGained(核心指标)
- 用户订阅频道的次数。This is a core metric and is subject to the Deprecation Policy.
频道可以在多个位置获得或失去订阅者,包括视频观看页面、频道页以及 YouTube 首页上显示的导视。 在频道报告中,此指标包括从上述任何位置获得的订阅者。不过,在通过video维度或filter参数限制响应仅包含特定视频数据的报告中,subscribersGained指标将仅包含指定视频的观看页面中的统计信息。 - subscribersLost(核心指标)
- 用户退订频道的次数。This is a core metric and is subject to the Deprecation Policy.
此指标的数据报告方式与subscribersGained指标类似。 在频道报告中,此指标包括通过任何机制(用户可通过这些机制退订频道)流失的订阅者。不过,在通过video维度或filter参数将响应限制为仅包含特定视频数据的报告中,此指标仅包含在指定视频的观看页面上退订的用户。 - videosAddedToPlaylists
- 视频被添加到任何 YouTube 播放列表的次数。这些视频可能已被添加到视频所有者的播放列表或其他频道的播放列表中。
该指标值包含视频被添加到默认播放列表(例如“稍后观看”播放列表)的次数。不过,此指标不会统计视频被自动添加到的播放列表,例如频道的上传视频播放列表或用户的观看记录。
此指标返回的是绝对数字,这意味着,如果用户将视频添加到播放列表,然后将其移除,接着又再次添加,则指标值会反映视频被添加到播放列表两次。我们不提供 2014 年 10 月 1 日之前的此指标数据。 - videosRemovedFromPlaylists
- 视频从任何 YouTube 播放列表中移除的次数。这些视频可能是从视频所有者的播放列表中移除的,也可能是从其他频道的播放列表中移除的。
该指标值包含视频从默认播放列表(如“稍后观看”播放列表)中移除的次数。
此指标返回的是绝对数字,这意味着如果用户将视频添加到播放列表、移除、再次添加,然后再次移除,则指标值会反映视频从播放列表中移除两次。我们不提供 2014 年 10 月 1 日之前的此指标数据。
播放列表指标
播放列表报告包含两种类型的指标,用于说明观看者如何与播放列表中的视频互动:
-
汇总视频指标提供用户活动和展示指标,这些指标是针对播放列表中所有视频汇总的,这些视频也归拥有该播放列表的频道所有。其他频道所拥有的视频的指标不会计入汇总数据。因此,如果某个频道创建的播放列表仅包含其他频道拥有的视频,则这些播放列表的报告不会提供这些指标的值。
-
播放列表内指标反映了用户在播放列表页面中的用户活动和互动情况。这些指标包括播放列表中所有视频的观看次数,无论这些视频属于哪个频道,但仅统计在播放列表中发生的观看次数。
以下大多数指标都是播放列表内指标;列表中的其余指标(例如 playlistSaves 指标)则与用户与播放列表本身(而非播放列表中的视频)的互动有关。因此,这些指标不会被归类为汇总视频指标或播放列表内指标。
- averageTimeInPlaylist
- 观看者在播放列表开始后观看其中视频的估算平均时长(以分钟为单位)。请注意,此指标仅包含在网页上发生的播放列表观看次数。
- playlistAverageViewDuration
- 每次观看播放列表时所带来的预估平均观看时长(以秒为单位)。请注意,此指标表示播放列表中单个视频的平均观看时长;相比之下,
averageTimeInPlaylist指标表示每位观看者观看整个播放列表的平均时长。此指标包含其他频道所拥有的播放列表视频的数据。 - playlistEstimatedMinutesWatched
- 用户通过播放列表观看播放列表内容的时长(以分钟为单位)。在其他情况下产生的观看时长(例如,观看者在观看其他播放列表中的同一视频时产生的观看时长)不会计入。此指标包含其他频道所拥有的播放列表视频的数据。
- playlistSaves
- 用户保存播放列表的净次数。如需详细了解已保存的播放列表,请参阅 YouTube 帮助中心。此指标会返回净变化值,这意味着,如果用户保存了某个播放列表,将其从已保存播放列表列表中移除,然后再次保存,则指标值会反映添加了一个播放列表保存。
- playlistStarts
- 播放列表被观看者播放的次数。请注意,此指标仅包含在网页上发生的播放列表观看次数。
- playlistViews
- 播放列表中的视频在播放列表中获得的观看次数。
此指标包含播放列表中其他频道所拥有的视频的数据。
- viewsPerPlaylistStart
- 每次播放列表开始后的平均视频观看次数。请注意,此指标仅包含在网页上发生的播放列表观看次数。
注释指标
注意:YouTube Analytics API 报告仅返回 2012 年 6 月 10 日之后的 annotationClickThroughRate 和 annotationCloseRate 指标数据。此外,自 2013 年 7 月 16 日起,YouTube Analytics API 报告仅返回其余注释指标的数据。
- annotationImpressions
- 注释的总展示次数。
- annotationClickableImpressions
- 出现且可点击的注释数量。
- annotationClicks
- 获得点击的注释数量。
- annotationClickThroughRate(核心指标)
- 观众点击的注释数量与可点击注释展示总次数的比率。This is a core metric and is subject to the Deprecation Policy. YouTube 帮助中心提供了有关创建注释和使用链接注释的更多信息。
- annotationClosableImpressions
- 出现且可关闭的注释数量。
- annotationCloses
- 已关闭的注释数量。
- annotationCloseRate(核心指标)
- 观看者关闭的注释数量与注释总展示次数的比率。This is a core metric and is subject to the Deprecation Policy.
卡片指标
YouTube 帮助中心提供了有关向视频添加卡片和 YouTube 数据分析卡片报告的更详细说明。
- cardImpressions
- 信息卡的展示次数。当卡片面板打开时,系统会为视频的每张卡片记录一次卡片展示。
- cardClicks
- 卡片被点击的次数。
- cardClickRate
- 卡片的点击率,计算方法为卡片点击次数与卡片展示次数的比率。
- 卡片宣传语的展示次数。一次视频观看可产生多次宣传语展示。
- 卡片宣传语获得的点击次数。卡片图标获得的点击次数将归于向用户展示的上一条宣传语。
- 卡片宣传语的点击率,计算方法是卡片宣传语的点击次数与卡片宣传语的总展示次数之比。
直播指标(同时观看人数)
- averageConcurrentViewers
- 特定视频的平均同时观看人数。此指标包含同看者(即多人一起通过电视屏幕观看广告的情况)。如果为报告指定了 livestreamPosition 维度,则
averageConcurrentViewers值指定特定片段期间的平均同时观看人数 - peakConcurrentViewers
- 特定视频的同时观看人数峰值。此指标包含同看者,即多人一起通过电视屏幕观看广告的情况。如果为报告指定了 livestreamPosition 维度,则
peakConcurrentViewers值指定视频特定片段期间的同时观看人数峰值。
观众黏度指标
- audienceWatchRatio
- 在视频中给定时间点观看视频的观看者的绝对比例。该比率的计算方法是:将视频中某个片段的观看次数与视频的总观看次数进行比较。
elapsedVideoTimeRatio维度用于标识指标对应的视频部分。
请注意,在一次视频观看中,视频的某个部分可能会被观看多次(或根本不被观看)。例如,如果用户多次倒回并观看视频的同一部分,则该部分视频的绝对比率可能会大于1。
以下示例说明了该值的计算方式:- 一个时长为 1 分钟的视频被观看了 100 次。一半的观看者在 15 秒后停止观看,其余观看者则看完整个视频。没有观看者多次观看视频的任何部分。在这种情况下,对于视频前四分之一的时间段,此指标的值为
1,而对于视频的其余部分,其值为0.50。 - 一个时长为 1 分钟的视频被观看了 100 次。所有观看者都看完了整个视频,但其中有 20 位观看者在看到视频的第 45 秒时,又跳回到视频的第 30 秒,然后看完了视频的其余部分。在这种情况下,对于视频前半部分或最后四分之一的时间段,该指标的值将为
1。不过,视频第三个四分之一时间段的值为1.2,因为 100% 的观看者都观看了该视频片段,但其中 20% 的观看者观看了该片段两次。
- 一个时长为 1 分钟的视频被观看了 100 次。一半的观看者在 15 秒后停止观看,其余观看者则看完整个视频。没有观看者多次观看视频的任何部分。在这种情况下,对于视频前四分之一的时间段,此指标的值为
- relativeRetentionPerformance
- 一种衡量指标,用于显示视频在播放期间相对于 YouTube 上所有时长相近的 YouTube 视频而言吸引观众继续观看的能力。该指标的值介于
0和1之间,用于标识视频在特定时间点的相对观众黏度。视频中的时间点由elapsedVideoTimeRatio维度提供。
值为0表示该视频在吸引观众继续观看方面的表现比任何其他时长相近的视频都要差,而值为1则表示该视频在吸引观众继续观看方面的表现比任何其他时长相近的视频都要好。中间值为0.5表示,在时长相近的视频中,有一半视频的观众黏度高于该值,另一半视频的观众黏度低于该值。
以下假设示例说明了这些值在报告中的显示方式。平均而言,在观看 10 分钟视频的观看者中,有 90% 的人在 3 分钟后仍在观看,有 70% 的人在 8 分钟后仍在观看。不过,对于某个时长为 10 分钟的视频,只有 80% 的观看者在 3 分钟后仍在观看,但所有这些观看者在 8 分钟后仍在观看。- 在视频播放到 3 分钟时,
elapsedVideoTimeRatio值对应的relativeRetentionPerformance指标值会低于0.5,因为此时该视频的效果低于平均水平。 - 在视频播放到 8 分钟时,
elapsedVideoTimeRatio值对应的relativeRetentionPerformance指标值会高于0.5,因为此时该视频的表现优于其他类似时长的视频。
- 在视频播放到 3 分钟时,
- startedWatching
- 视频的特定片段在视频播放期间作为第一个片段被观看的次数。
例如,假设视频 X 的时长为 5 分钟。为了生成此报告,YouTube 会将视频分成 100 个 3 秒长的片段,这些片段通过 elapsedVideoTimeRatio 维度进行标识。观看者访问 YouTube 并观看视频的前 1 分 10 秒,其中包含视频前 24 个片段的全部或部分内容。在随后访问 YouTube 时,观看者观看了视频的其余部分,从第 24 个片段开始继续播放,一直播放到第 100 个片段。
此示例会生成以下观看指标值:- 对于片段 1 和 24,
startedWatching指标的值为1,对于所有其他片段,指标值为0。 - 对于细分 24 和 100,
stoppedWatching指标的值为1,对于所有其他细分,指标值为0。 - 对于片段 24,
totalSegmentImpressions指标的值为2,对于所有其他片段,指标值为1。
- 对于片段 1 和 24,
- stoppedWatching
- 视频的特定片段在视频播放期间作为最后一个片段被观看的次数。如需查看此指标值的计算示例,请参阅
startedWatching指标的定义。 - totalSegmentImpressions
- 视频中某个片段的观看次数。如需查看此指标值的计算方式示例,请参阅
startedWatching指标的定义。请注意,观看者可以在同一次播放中多次观看视频的同一片段。
会员取消指标
- membershipsCancellationSurveyResponses
- 在报告期内,取消了指定频道会员资格的 YouTube 用户完成的调查问卷数量。
估算收入指标
注意:估算收入指标在月末可能会有所调整,而且不包含合作伙伴出售或投放的广告所产生的收入。如需了解有关估算收入数据的更多信息和注意事项,请参阅 YouTube 帮助中心。
currency 参数,以便您检索其他币种的估算收入数据。- estimatedRevenue(核心指标)(之前名为
earnings) - 在所选日期范围和区域内,通过 Google 出售的所有广告来源以及非广告来源获得的估算净收入总额。
This is a core metric and is subject to the Deprecation Policy.
估算收入指标在月末可能会有所调整,而且不包含合作伙伴出售或投放的广告所产生的收入。
- estimatedAdRevenue(之前名为
adEarnings) - 在选定的日期范围和区域内,通过 Google 出售的所有广告来源产生的总估算净收入。
估算收入指标在月末可能会有所调整,而且不包含合作伙伴出售或投放的广告所产生的收入。 - estimatedRedPartnerRevenue(之前名为
redPartnerRevenue) - 在所选报告维度下,通过 YouTube Premium(以前称为“YouTube Red”)订阅赚取的估算收入总额。该指标的值反映了音乐和非音乐内容的收入,并会在月末进行调整。
广告效果指标
- grossRevenue
- 在选定的日期范围和区域内,由 Google 出售或 DoubleClick 合作伙伴出售的所有广告带来的估算总收入(以美元为单位)。总收入在月末可能会有所调整,而且不包含合作伙伴投放的广告所产生的收入。总收入不应与估算收入或净收入混淆,后者会考虑您的所有权份额和收益分成协议。
- cpm(之前名为
impressionBasedCpm) - 每千次广告展示的估算总收入。
- adImpressions(之前名为
impressions) - 经过验证的广告展示次数。
- monetizedPlaybacks
- 观看者播放您的视频并至少看到过一次广告展示的次数。如果观看者看到前贴片广告,但在您的视频开始播放之前就退出了观看,也会被计为一次创收播放。此数字的预期估计误差为 ±2.0%。
- playbackBasedCpm
- 每千次播放的估算总收入。