本文档定义了您可以使用 YouTube Analytics API 检索的指标。此 API 支持实时查询,以生成自定义 YouTube 数据分析报告。
指标是指对用户活动、广告效果或估算收入的各项衡量指标。用户活动指标包括视频观看次数和评分(顶和踩等)等。
核心指标
虽然 YouTube Analytics API 受服务条款中规定的弃用政策约束,但非核心指标(和非核心维度)不受该政策影响。在本页面的定义中,任何明确显示为核心指标的指标都是这样。
下表列出了 API 的核心指标。
annotationClickThroughRate
annotationCloseRate
averageViewDuration
comments
dislikes
estimatedMinutesWatched
estimatedRevenue
likes
shares
subscribersGained
subscribersLost
viewerPercentage
views
注意:以下核心指标已被完全弃用:
earnings
核心指标已于 2016 年 8 月 4 日弃用,并将其重命名为estimatedRevenue
。根据服务条款中规定的弃用政策,在 2017 年 8 月 10 日之前,您可以同时支持earnings
和estimatedRevenue
指标。favoritesAdded
和favoritesRemoved
核心指标已于 2015 年 3 月 31 日弃用。您只能通过 YouTube Analytics API 检索这些指标。
如需了解详情,请参阅需遵循弃用政策的 YouTube API 列表。
查看指标
- 观看次数(核心指标)
- 视频的观看次数。在播放列表报告中,该指标可指示视频在播放列表环境中的观看次数。YouTube 帮助中心提供了有关如何报告观看次数的更多信息。This is a core metric and is subject to the Deprecation Policy.
- redViews
- YouTube Premium(以前称为 YouTube Red)会员观看视频的次数。
- 唯一身份用户(已于 2016 年 9 月 27 日弃用)
- 观看视频的唯一身份观看者人数。这种计算基于唯一身份 Cookie 的数量,因此会统计使用多台设备或多个浏览器的用户人数。
uniques
指标已于 2016 年 9 月 27 日弃用。它不是核心指标,并且在 2016 年 10 月 31 日之前均受支持。 - 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.
- 顶的次数(核心指标)
- 用户对视频给予好评的次数,表示他们喜欢相应视频的次数。This is a core metric and is subject to the Deprecation Policy.
- 踩(核心指标)
- 用户对视频给予差评,表示他们踩了视频的次数。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. - 订阅人数(核心指标)
- 用户订阅频道的次数。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
参数将响应限制为仅包含特定视频的数据,则此指标仅包括已退订指定视频的观看页面的用户。 - videosAddedTo 播放列表
- 视频添加到任意 YouTube 播放列表的次数。这些视频可能已添加到视频所有者的播放列表或其他频道的播放列表中。
该指标值确实包括视频被添加到默认播放列表(如“稍后观看”播放列表)的次数。但是,系统不会统计自动添加到视频的播放列表,例如频道的上传内容播放列表或用户的观看记录。
该指标会返回一个绝对数字,也就是说,如果用户在将视频添加到播放列表后将其移除,然后重新添加,则此指标值反映的是该视频被添加到播放列表中两次。系统无法提供 2014 年 10 月 1 日之前的该指标数据。 - 请从视频中移除播放列表
- 视频从所有 YouTube 播放列表中移除的次数。这些视频可能已被从视频所有者的播放列表或其他频道的播放列表中移除。
该指标值包括从默认播放列表(如“稍后观看”播放列表)中移除视频的次数。
该指标会返回一个绝对数字,也就是说,如果用户向播放列表中添加了视频,然后将其移除,并再次将其移除,则该指标值反映的是系统从播放列表中移除两次。系统无法提供 2014 年 10 月 1 日之前的该指标数据。
已弃用的互动指标
以下指标都是已于 2015 年 3 月 31 日弃用的核心指标。
- 添加了收藏项(核心指标)(已于 2015 年 3 月 31 日弃用)
- 用户将视频标记为收藏视频的次数。如需了解详情,请参阅 YouTube 帮助中心。This is a core metric and is subject to the Deprecation Policy.
- favoritesRemoved(核心指标)(于 2015 年 3 月 31 日弃用)
- 用户从收藏的视频列表中移除视频的次数。如需了解详情,请参阅 YouTube 帮助中心。This is a core metric and is subject to the Deprecation Policy.
播放列表指标
- 播放列表开始次数
- 观看者发起播放列表播放的次数。请注意,此指标仅包含网络上发生的播放列表观看次数。
- viewsPerPlaylistStart 次数
- 每次启动播放列表时所发生的平均视频观看次数。请注意,此指标仅包含网络上发生的播放列表观看次数。
- averageTimeInPlaylist
- 观看者观看播放列表中视频后的平均观看时间(以分钟为单位)。请注意,此指标仅包含网络上发生的播放列表观看次数。
注解指标
注意:YouTube Analytics(分析)API 报告只会返回自 2012 年 6 月 10 日起的 annotationClickThroughRate
和 annotationCloseRate
指标的数据。此外,YouTube Analytics API 报告仅返回截至 2013 年 7 月 16 日的其余注释数据。
- annotationImpressions
- 注释总展示次数。
- annotationClickableImpression
- 显示且可以点击的注释的数量。
- 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
- 卡片点击率,计算方法为卡片点击次数与卡片展示次数的比率。
- 卡片宣传语的展示次数。一次视频观看可产生多次宣传片展示。
- 卡片宣传语获得的点击次数。卡片图标获得的点击次数将归功于用户最后一次展示的宣传语。
- 卡片宣传语的点击率,计算方式为:卡片宣传语的点击次数与卡片宣传语总展示次数。
观众黏度指标
- audienceWatchRatio
- 在视频的指定时间点观看视频的绝对观看者人数。该比率的计算方法是:将一部分视频的观看次数与视频的总观看次数进行比较。
elapsedVideoTimeRatio
维度用于标识视频中与指标对应的部分。
请注意,在某一视频观看过程中,视频的一部分可能会被观看多次(或者根本无法观看)。例如,如果用户快退并多次观看视频的同一部分,则视频的该部分的绝对比率可能大于1
。
以下示例说明了如何计算值:- 一分钟的视频获得了 100 次观看。一半的观看者在 15 秒后停止观看,其余观看者观看视频。没有任何观看者多次观看视频的任何部分。在本例中,对于视频第一季度中的时间段,该指标的值将为
1
,而对于视频的其余部分,该指标的值将为0.50
。 - 一分钟的视频获得了 100 次观看。所有观看者都看完了整个视频,但 20 名观看者会观看视频的 45 秒标记,然后跳回视频的 30 秒标记,然后观看视频的其余部分。在这种情况下,指标在视频前半部分或下四分之一处的时间段值为
1
。然而,在视频第三四分之一的时间段内,该值为1.2
,因为 100% 的观看者观看了该片段,但 20% 的观看者观看了该片段两次。
- 一分钟的视频获得了 100 次观看。一半的观看者在 15 秒后停止观看,其余观看者观看视频。没有任何观看者多次观看视频的任何部分。在本例中,对于视频第一季度中的时间段,该指标的值将为
- relative 留存率 Performance
- 此指标衡量的是,与 YouTube 上所有类似时长的视频相比,视频在播放期间留住观看者的程度。该指标的值介于
0
和1
之间,用于标识视频在给定时间点的相对保留性能。视频中的点由elapsedVideoTimeRatio
维度提供。
值0
表示在留住观看者方面,视频比在任何其他类似时长的视频上表现差,而值为1
表示视频在吸引观看者方面比任何其他时长相近的视频效果更佳。中位数值为0.5
表示时长相近的视频中,有一半的视频在留住观看者方面效果较好;而在一半的视频中,观看者的观看效果却更好。
下面的假设示例说明了这些值在报告中的显示方式。平均而言,90% 的观众在观看 10 分钟的视频后,会在 3 分钟后仍在观看,而 70% 的观看者在 8 分钟后仍会继续观看。但是,对于时长 10 分钟的特定视频,只有 80% 的观看者在 3 分钟后仍在观看,但这些观看者在 8 分钟之后仍在观看。- 在
elapsedVideoTimeRatio
值(与视频开始三分钟后所对应时间点的对应值)下,relativeRetentionPerformance
指标的值将低于0.5
,因为此时视频的效果低于平均视频表现。 - 在与视频的第 8 分钟对应的点的
elapsedVideoTimeRatio
值下,relativeRetentionPerformance
指标的值将高于0.5
,因为此时视频的效果优于其他时长相似的视频。
- 在
估算收入指标
注意:估算收入指标在月底可能会有所调整,而且不包含合作伙伴出售的广告和合作伙伴投放的广告。请访问 YouTube 帮助中心,了解有关估算收入数据的更多信息和说明。
默认情况下,所有估算收入数据都以美元报告。不过,YouTube 数据分析 API 支持使用
currency
参数了解部分估算收入和广告效果指标,以便您检索其他货币的估算收入数据。- 估算收入 (核心指标) (之前名为
earnings
) - 在选定日期范围和区域内,Google 出售的所有来源以及非广告来源带来的总净收入估算值。
This is a core metric and is subject to the Deprecation Policy.
估算收入指标在月底可能会有所调整,而且不包含合作伙伴出售的广告和合作伙伴投放的广告。
- estimatedAdRevenue (以前称为
adEarnings
) - Google 出售的所有广告资源在选定日期范围和区域内产生的估算总净收入。
估算收入指标在月底可能会有所调整,而且不包含合作伙伴出售和投放的广告。 - estimatedRedPartnerRevenue (之前名为
redPartnerRevenue
) - 所选报告维度从 YouTube Premium(以前称为 YouTube Red)订阅中获得的总估算收入。该指标的值反映了音乐和非音乐内容的收入,并且可能在月底进行调整。
广告效果指标
- 总收入
- 在所选日期范围和区域内,Google 出售或 DoubleClick 合作伙伴出售的所有广告所带来的估算总收入(美元)。总收益以月末调整为准,且不涵盖合作伙伴投放的广告。总收入与估算收入(又称净收入)有所不同,后者会将您的所有权份额和收益分成协议的分成列入计算,请勿将二者混淆。
- cpm (之前名为
impressionBasedCpm
) - 每千次广告展示的估算总收入。
- adImpressions (之前名为
impressions
) - 投放的已验证广告展示次数。
- monetizedPlaybacks
- 观看者播放视频并至少看到一次广告展示的情况数量。如果向观看者播放了前贴片广告,但您的视频还没开始观看就停止了观看,则计为一次创收播放。此数字的预计误差为 ±2.0%。
- playbackBasedCpm
- 每千次播放的估算总收入。