Metrics

本文档定义了您可以使用 YouTube Analytics API 检索的指标。此 API 支持实时查询，以生成自定义 YouTube 数据分析报告。

指标是对用户活动、广告效果或估算收入的单独衡量。用户活动指标包括视频观看次数和评分（顶和踩）等信息。

核心指标

尽管 YouTube Analytics API 需遵守服务条款中规定的弃用政策，但非核心指标（和非核心维度）不受此政策限制。在本页的定义中，任何属于核心指标的指标都会明确标识出来。

以下列表列出了该 API 的核心指标。

注意：以下核心指标已完全弃用：
  • earnings 核心指标已于 2016 年 8 月 4 日弃用，并重命名为 estimatedRevenue。根据服务条款中定义的弃用政策，在 2017 年 8 月 10 日之前，系统同时支持 earnings 和 estimatedRevenue 指标。
  • favoritesAdded 和 favoritesRemoved 核心指标已于 2015 年 3 月 31 日弃用。这些指标只能通过 YouTube Analytics API 检索。

如需了解详情，请参阅受弃用政策约束的 YouTube API 列表。

查看指标

观看次数 （核心指标）
此指标在不同类型的报告中表示不同的数字：
  • 在视频报告中，此指标用于指定视频的观看次数。
  • 在不使用 isCurated 维度的播放列表报告中，此指标用于指定播放列表中视频的总观看次数，而不管这些观看是否发生在播放列表的上下文中。请注意，该指标值仅包括频道所有者视频的观看次数。

    在这些报告中，playlistViews 指标表示播放列表视频在特定播放列表中获得的观看次数。
  • 在使用 isCurated 维度的播放列表报告中，此指标表示视频在特定播放列表中被观看的次数。请注意，这些报告不支持 playlistViews 指标。
This is a core metric and is subject to the Deprecation Policy.
playlistViews
此指标在播放列表指标部分中定义。
redViews
YouTube Premium（以前称为 YouTube Red）会员观看视频的次数。
uniques（已于 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.
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 日之前的该指标数据。

已弃用的互动指标

以下指标都是已于 2015 年 3 月 31 日弃用的核心指标。

favoritesAdded （核心指标）（已于 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.

播放列表指标

播放列表报告包含两种类型的指标，这些指标说明了观看者与播放列表中的视频的互动情况：

  • 汇总的视频指标会提供用户活动和展示次数指标，这些指标会针对播放列表中的所有视频，以及拥有该播放列表的频道的所有视频提供汇总。汇总时不会计算其他频道所拥有的视频的指标。因此，如果某个频道创建的播放列表只包含其他频道所拥有的视频，那么这些播放列表的报告将不会提供这些指标的值。

    如需了解支持的汇总视频指标的定义，请参阅本文档的观看次数指标和观看时长指标部分。

  • 播放列表内指标反映了播放列表页面中的用户活动和互动度。这些指标包括播放列表中所有视频的观看次数，无论它们归哪个频道所有，但仅统计在播放列表中出现的观看次数。

下面列出的大多数指标都是播放列表内指标；列表中的其余指标（如 playlistSaves 指标）则是关于用户与播放列表本身（而非播放列表中的视频）的互动。因此，这些指标不会以汇总的视频指标或播放列表内指标为特征。

averageTimeInPlaylist
观看者在播放列表启动后观看播放列表中的视频的估算平均时长（以分钟为单位）。请注意，此指标仅包含网上的播放列表观看次数。
playlistAverageViewDuration
每次播放列表观看带来的估算平均时长（以秒为单位）。请注意，此指标表示播放列表中各个视频的平均观看次数；而 averageTimeInPlaylist 指标则表示每位观看者观看整个播放列表的平均时间。此指标包含其他频道拥有的播放列表视频的数据。
playlistEstimatedMinutesWatched
用户观看播放列表中内容的分钟数。系统不会统计在其他情境中发生的观看时长，例如，观看者在其他播放列表中观看同一视频时产生的观看时长。此指标包含其他频道拥有的播放列表视频的数据。
playlistSaves
用户保存播放列表的净次数。请参阅 YouTube 帮助中心，详细了解保存的播放列表。此指标会返回净变化值，也就是说，如果用户保存了某个播放列表，将其从已保存的播放列表列表中移除，然后再次保存，则该指标值反映添加了一次播放列表保存操作。
playlistStarts
观看者启动播放列表播放的次数。请注意，此指标仅包含网上的播放列表观看次数。
playlistViews
用户在该播放列表中观看该播放列表中的视频的次数。 此指标包含其他频道拥有的播放列表视频的数据。
viewsPerPlaylistStart
播放列表的每次启动带来的平均视频观看次数。请注意，此指标仅包含网上的播放列表观看次数。

注解指标

注意：YouTube Analytics API 报告仅返回截至 2012 年 6 月 10 日的 annotationClickThroughRate 和 annotationCloseRate 指标数据。此外，YouTube Analytics API 报告仅返回截至 2013 年 7 月 16 日其余注释指标的数据。

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
卡片的点击率，计算方式是卡片点击次数与卡片展示次数的比率。
cardTeaserImpressions
卡片宣传语的展示次数。一次视频观看可以带来多次宣传语展示。
cardTeaserClicks
卡片宣传语获得的点击次数。卡片图标获得的点击次数将归于向用户展示的上一条宣传语。
cardTeaserClickRate
卡片宣传语的点击率，计算方式是卡片宣传语获得的点击次数与卡片宣传语的总展示次数的比率。

观众黏度指标

audienceWatchRatio
在视频的指定时间点观看视频的观看者的绝对比例。该比率的计算方式是将视频中某一部分的观看次数与该视频的总观看次数相比较。elapsedVideoTimeRatio 维度用于标识视频中与此指标对应的部分。

请注意，视频的某个部分可能会在指定视频观看事件中被多次观看（或根本不观看）。例如，如果用户快退并多次观看视频的同一部分，则该部分视频的绝对比率可能会大于 1。

以下示例说明了该值的计算方式：
  • 一分钟视频的观看次数为 100 次。一半的观看者在 15 秒后停止观看，其余的观看者则看完整个视频。观看者均不会重复观看视频的任何部分。在本例中，对于视频前四分之一的时间段，此指标的值为 1；对于视频的其余部分，其值为 0.50。
  • 一分钟视频的观看次数为 100 次。所有观众观看了整个视频，但有 20 人观看了视频的 45 秒标记，然后跳回视频的 30 秒标记，然后观看视频的剩余部分。在本例中，对于视频前半部分或后四分之一的时间段，该指标的值将为 1。然而，对于视频处于第三四分位的时间段，该值将为 1.2，因为 100% 的观看者观看了该视频的该片段，但有 20% 的观看者观看了该片段两次。
relativeRetentionPerformance
这项衡量指标显示了与所有时长相近的 YouTube 视频相比，某个视频在播放期间留住观看者的程度。该指标的值介于 0 和 1 之间，用于标识视频在视频给定时间点的相对黏度表现。视频中的点由 elapsedVideoTimeRatio 维度提供。

值为 0 表示此视频在观看者留住观看者方面表现比其他任何时长相近的视频更差，而值为 1 表示该视频对观看者的黏度高于其他任何时长相近的视频。中间值为 0.5 表示在时长相近的视频中，一半的视频在留住观看者方面表现较好，而一半的视频在留住观看者方面表现较差。

以下假设示例说明了这些值在报告中可能的显示方式。平均而言，在观看时长为 10 分钟的视频的观看者中，90% 的观看者在 3 分钟后仍会继续观看，70% 的观看者在 8 分钟后仍会继续观看。然而，对于长度为 10 分钟的特定视频，只有 80% 的观看者在 3 分钟后仍会继续观看，但这些观看者在 8 分钟后仍会继续观看。
  • 如果视频时长达到 3 分钟，则对应的 elapsedVideoTimeRatio 值会变为 relativeRetentionPerformance 指标的值低于 0.5，因为此时视频表现不及视频平均水平。
  • 视频进入 8 分钟后，视频时长为 8 分钟时，对应时间点的 elapsedVideoTimeRatio 值会变为 relativeRetentionPerformance 指标的值，该值会高于 0.5，因为届时视频的表现优于其他时长相近的视频。

估算收入指标

注意：“估算收入”指标受月末调整的影响，而且不包括合作伙伴出售的广告和合作伙伴投放的广告。有关估算收入数字的其他信息和注意事项，请参阅 YouTube 帮助中心。

默认情况下，所有估算收入数据都会以美元进行报告。不过，对于一些估算收入和广告效果指标，YouTube Analytics API 支持使用 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
每千次播放的估算总收入。