YouTube Analytics API - Data Model

借助 YouTube Analytics API，您可以生成包含 YouTube 数据分析数据的自定义报告。该 API 支持频道报告和内容所有者报告。报告字段分为维度和指标：

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

    在报告中，每行数据都具有唯一的维度值组合。因此，您为报告选择的维度会决定 YouTube 如何计算相应报告中指标的值。

  • 指标是与用户活动、广告效果或估计收入相关的单个衡量值。用户活动指标包括视频观看次数和评分（赞和踩）等。

Analytics API 提供过滤和排序参数，因此调用应用无需原生支持这些功能。您还可以使用该 API 检索 YouTube 数据分析群组的数据，其中群组是指最多包含 500 个视频、播放列表、频道或资产的自定义集合。

选择报告参数

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

  • startDate 和 endDate 参数用于指定报告将包含数据的时间段。实际上，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 移动设备上的观看次数是多少？）

    • 频道所有者可以过滤请求，以仅返回特定国家/地区的值。（报告期内，加拿大每天的视频观看次数是多少？）

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

      此外，如果 video 过滤条件指定了多个值，则还可以将 video 指定为维度。这意味着 dimensions 参数也支持值 deviceType,video 和 day,deviceType,video。

      • 如果频道所有者在维度列表中添加了视频，则指标会为每个视频指定单独的值。（2015 年 6 月 1 日，视频 XYZ 在游戏机上的观看次数是多少？）
      • 如果频道所有者未在维度列表中添加视频，则相应指标会指定涵盖所有指定视频的总值。（2015 年 6 月 1 日，视频 ABC、DEF 和 XYZ 在游戏机上的观看次数分别是多少？）

检索报告

如需检索报告，请向 API 的 reports.query 方法发送经过授权的 GET 请求，并指定用于定义要检索的报告的参数。

如需查看 API 支持的报告列表，请参阅频道报告和内容所有者报告文档。每个报告定义都会确定报告允许的 metrics、dimensions 和 filters 参数值。

最佳做法

使用 YouTube Analytics API 的应用应始终遵循以下做法：

  • 使用响应的标题行确定报告列的顺序。例如，不要因为观看次数是报告说明中列出的第一个指标，就认为它会是响应中返回的第一个指标。请改用响应的标题行来确定哪个列包含相应数据。
  • 使用 YouTube Data API 检索 YouTube Analytics API 响应中标识的资源的其他元数据。如 YouTube API 服务开发者政策（第 III.E.4.b 条至第 III.E.4.d 条）中所述，API 客户端必须在 30 天后删除或刷新从相应 API 存储的资源元数据。

汇总指标和已删除的内容

YouTube Analytics API 响应不包含已删除项目的指标细分数据。例如，如果频道所有者删除了某个视频，那么在按视频返回指标的 API 响应中，该视频将不再列出。不过，汇总一组资源指标的报告仍会包含与已删除项目相关的指标。

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

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

数据匿名化

如果相关指标达不到特定阈值，YouTube 数据分析中可能会有一些数据因受到限制而不予显示。这种情况可能会出现在各种报告中。实际上，如果出现以下情况，报告可能不会包含所有数据（或不包含任何数据）：

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

    或

  2. 您选择了特定过滤条件或维度（例如流量来源或国家/地区），但其值未达到特定阈值。

在数据因受限而不予显示时，不同报告中显示的总计数可能会有所不同，具体取决于这些报告汇总数据的方式。

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

在此示例中，第一份报告会显示该视频的观看次数为 1, 000 次。第二个报告只会显示该视频在美国被观看了 500 次，在加拿大被观看了 498 次。由此可看出，这两个报告中的总观看次数之间存在差异。请注意，第二个报告不会显示发生的另外两次观看（也不会显示发生在法国的任何观看次数）。

YouTube 不会公布限制数据的实际阈值，且会酌情调整阈值。

受限的数据类型

在 YouTube 数据分析报告中，以下数据可能会受到限制不予显示：

  • 人口统计学特征数据，例如年龄和性别。
  • 地理位置数据，包括与观看者所在国家/地区相关的指标或维度，例如观看者所在的国家/地区。不过请注意，报告不会对收入指标应用地理位置阈值。
  • 与特定流量来源相关的指标，例如促成视频观看的搜索字词或外部网址。例如，如果某个搜索字词或网址带来的观看次数非常少，则不会显示在报告中，但您仍会看到能为您的内容吸引大量观看者的字词和网址。

如需详细了解 YouTube 数据分析报告中因受限而不予显示的数据，请参阅 YouTube 帮助中心。

配额用量

您发出的每个 API 请求都会计入 API 用量配额。配额限制会显示在 Google API 控制台的配额面板中。