YouTube Analytics API - Data Model

您可以使用 YouTube Analytics API 生成包含 YouTube 数据分析数据的自定义报告。该 API 支持频道和内容所有者的报告。报告字段的特征为维度或指标:

  • 维度是用于汇总数据的常见条件,例如执行操作的日期或用户所在的国家/地区。

    在报表中,每行数据都有一个唯一的维度值组合。因此,您为报告选择的维度将决定 YouTube 如何计算该报告中指标的值。

  • 指标是与用户活动、广告效果或估算收入相关的个人衡量指标。用户活动指标包括视频观看次数和评分(顶和踩等)等。

Google Analytics(分析)API 提供过滤和排序参数功能,因此调用应用无需原生支持这些功能。借助该 API,您还可以检索 YouTube 数据分析组中的数据,其中的数据组最多可包含 500 个视频、播放列表、频道或资产。

选择报告参数

当您使用 API 的 reports.query 方法请求报告时,API 请求将包含五个用于确定报告值计算方式的参数:

  • startDateendDate 参数用于指定报表包含数据的时间段。实际上,API 响应包含截至查询指定当天(在此之前的所有查询指标)可用的数据。

  • metrics 参数用于指定将纳入报表的衡量指标。在渠道报告中,指标用于衡量用户活动,并且包含观看次数顶的次数等值。有些指标还会衡量广告效果或估算收入。

  • dimensions 参数说明指标的分组方式。

  • filters 参数说明报告数据的过滤方式。例如,您可以对报告进行过滤,使其仅包含特定国家/地区、视频或视频组的指标,而不是返回某个频道的所有数据。

    注意:您可以使用 API 为视频播放列表频道过滤条件指定多个值。如果您这样做,那么您还可以在维度列表中添加该过滤条件,这样返回的指标也会按视频、播放列表或频道分组。

报告选项示例

例如,假设某个频道所有者想要检索视频设备类型报告,以确定该频道的视频在移动设备、游戏机、电视等平台上的观看次数。

  • 频道所有者将 startDate 参数设置为 2015-06-01,并将 endDate 参数设置为 2015-07-31。根据这些值,报告将包含为期两个月的数据。

  • 设备类型报告支持观看次数estimatedMinutesWatched 指标,因此频道所有者将 metrics 参数设为 views,estimatedMinutesWatched

  • 对于 dimensions 参数,频道所有者有多种选项。其中有两个已经显示在下表中,第三个部分将在本部分后面的 filters 参数值说明中进行讨论。

    • 将参数值设为 deviceType 表示在报告涵盖的整个时间段内,观看次数和观看时长将按设备类型分组。因此,通过该值,报告数据可解答以下问题:

      • 在 2015 年 6 月 1 日至 2015 年 7 月 31 日期间,该频道的视频被观看了多少次?
      • 在 2015 年 6 月 1 日至 2015 年 7 月 31 日期间,该频道的视频在游戏机上获得了多少次观看?

      该报告实际上会包含每种设备类型的总观看次数和观看时长。

    • 将参数值设为 day,deviceType 意味着,在报表期内,系统会按设备类型分别计算观看次数和观看时长。因此,通过该值,报告数据可解答以下问题:

      • 在 2015 年 6 月 1 日,该频道的视频被观看了多少次?
      • 2015 年 7 月 14 日,该频道的视频被观看了多少次?

  • 最后,filters 参数允许渠道所有者限制报告,使其仅包含符合特定过滤条件值的数据。报告支持过多的过滤选项,无法全部说明,因此这些示例只是您可以生成的部分报告。

    • 频道所有者可以过滤请求,以便只返回 Android 操作系统的值。(在报告期内,Android 移动设备上出现了多少次观看?)

    • 频道所有者可过滤请求,以便只返回特定国家/地区的值。(在报告期内,加拿大用户每天的视频观看次数是多少?)

    • 频道所有者可过滤请求,以便仅返回特定视频的值。不过,“视频”过滤条件支持逗号分隔值列表,因此该报告实际上可能会包含许多视频的数据。

      此外,如果“视频”过滤条件指定了多个值,则还可将“视频”指定为维度。也就是说,dimensions 参数也支持 deviceType,videoday,deviceType,video 值。

      • 如果频道所有者在维度列表中包含视频,那么指标将为每个视频指定单独的值。(2015 年 6 月 1 日,XYZ 在游戏机上观看了多少次?)
      • 如果频道所有者没有在维度列表中包含“视频”,则这些指标指定涵盖所有指定视频的总值。(2015 年 6 月 1 日,ABC、DEF 和 XYZ 在游戏机上观看了多少次?)

检索报告

要检索报告,请向 API 的 reports.query 方法发送经过授权的 GET 请求,并指定定义您想要检索的报告的参数。

请参阅渠道报告内容所有者报告文档,获取 API 支持的报告列表。每个报告定义都会标识报告允许 metricsdimensionsfilters 参数的值。

最佳实践

使用 YouTube Analytics API 的应用必须始终遵循以下做法:

  • 使用响应的标题行来确定报告的列顺序。例如,不要假设“观看次数”是响应中返回的第一个指标,因为它是报告说明中列出的第一个指标。正确的做法是,根据响应的标题行来确定哪个列包含相应数据。
  • 您可以使用 YouTube Data API 来检索 YouTube 数据分析 API 响应中标识的资源的其他元数据。如 YouTube API 服务开发者政策(第 III.E.4.b 至 III.E.4.d 节)中所述,API 客户端必须在 30 天后从该 API 中删除或刷新存储的资源元数据。

汇总指标和已删除的内容

YouTube 数据分析 API 响应不包含已删除项的指标细分。例如,如果频道所有者删除了某个视频,则该视频就不会再列在返回逐个视频指标的 API 响应中。但是,汇总一组资源的指标的报告仍然包含与已删除内容相关的指标。

例如,假设某个频道所有者检索了两份报告。第一份报告列出频道的所有视频在特定时间段内的每日总观看次数。第二份报告列出了同一时间段内每个视频的每日总观看次数。

在这种情况下,第一份报告中的数字将包含之后被删除的视频的观看次数,因为第一份报告包含每日汇总数据。但是,第二份报告不包含与已删除内容相关联的观看次数,因为第二份报告是按视频列出的观看次数。因此,如果频道在报告涵盖的时间段内删除了视频,那么第一个报告中报告的每日总观看次数可能会高于第二个报告中每日视频专用观看次数的总和。

数据匿名化

当指标未达到特定阈值时,部分 YouTube 数据分析数据将受到限制。各种报告中可能会发生这种情况。实际上,这意味着在以下情况下,报告可能不会包含您的所有(或任何)数据:

  1. 视频或频道在指定时间段内的流量有限;

  2. 您选择的过滤条件或维度(例如流量来源或国家/地区)的值未达到特定阈值。

如果数据有限,则不同报告中报告的总数可能会有所不同,具体取决于这些报告汇总数据的方式。

例如,假设某个频道所有者检索了两份报告。第一个报告列出了特定视频的总观看次数,而第二个报告则按国家/地区列出了该视频的总观看次数。在该指定时间段内,假设视频的观看次数为 1000 次,其中美国为 500 次,加拿大为 498 次,法国为 2 次。

在此示例中,第一个报告会指明视频的观看次数为 1000 次。第二份报告仅指明视频在美国获得了 500 次观看,加拿大则是 498 次。因此,这两种报告中的总观看次数会有所不同。请注意,第二份报告不包含任何表明还发生了另外两次观看(或者任何观看都发生在法国)的情况。

数据受限的实际阈值无法发布,并且可能会由 YouTube 自行决定更改。

受限数据类型

在 YouTube 数据分析报告中,以下数据可能会受到限制:

  • 受众特征数据,例如年龄和性别。
  • 地理位置数据,包括与观看者所在的国家或地区相关的指标或维度,例如观看者所在的国家或地区。不过请注意,报告不会将地理位置阈值应用于收入指标。
  • 与特定流量来源相关的指标,例如促成用户观看您的视频的搜索字词或外部网址。例如,报告中只会带来带来极少观看次数的搜索字词和网址,不过您仍会看到吸引大量观看者浏览的字词和网址。

如需详细了解 YouTube 数据分析报告中的有限数据,请访问 YouTube 帮助中心

配额用量

您发出的每个 API 请求将计为一个 API 用量配额单位。配额限制在 Google API 控制台的配额面板中显示。