Metrics

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

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

核心指标

虽然 YouTube Analytics API 受《服务条款》中定义的弃用政策的约束，但非核心指标（和非核心维度）不受该政策的约束。在此页面上的定义中，任何核心指标都会明确标识为核心指标。

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

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

观看次数指标

engagedViews （核心指标）
频道视频播放到第一帧之后或用户点击/轻按以播放的次数。
views （核心指标）
此指标在不同类型的报告中表示不同的数字。 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.
赞 （核心指标）
用户通过给出好评表示喜欢某个视频的次数。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.
shares （核心指标）
用户通过 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
每次播放列表启动时发生的平均视频观看次数。请注意， 此指标仅包括在网络上发生的播放列表观看次数。

注释指标

注意 ：自 2012 年 6 月 10 日起，YouTube Analytics API 报告仅返回 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
卡片的点击率，计算方式为卡片点击次数与卡片展示次数的比率。
cardTeaserImpressions
卡片宣传语的展示次数。观看一次视频可能会产生多次宣传语展示。
cardTeaserClicks
卡片宣传语的点击次数。卡片图标获得的点击次数将归于向用户展示的上一条宣传语。
cardTeaserClickRate
卡片宣传语的点击率，计算方式为卡片宣传语的点击次数与卡片宣传语展示总次数的比率。

直播指标（同时观看人数）

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% 的观看者观看了该片段两次。
relativeRetentionPerformance
一种衡量指标，用于显示视频在播放期间相对于 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，因为此时视频的表现优于其他时长相近的视频。
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。
stoppedWatching
视频的特定片段在 视频播放期间最后被观看的次数。如需查看此指标值的计算示例，请参阅 startedWatching 指标的定义。
totalSegmentImpressions
视频的特定片段被观看的次数。如需查看此指标值的计算示例，请参阅 startedWatching 指标的定义。请注意，观看者可以在同一播放期间多次观看视频的同一片段。

会员取消指标

membershipsCancellationSurveyResponses
在报告期内，取消 指定频道会员资格的 YouTube 用户完成的调查数量。

估算收入指标

注意 ：估算收入指标受月末调整的影响，不包括合作伙伴出售的广告资源带来的收入和合作伙伴投放的广告带来的收入。如需了解有关估算收入数字的其他信息和注意事项，请访问 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
每千次播放的估算总收入。