修订历史记录

此页面列出了 YouTube Reporting API 和 YouTube Analytics API 的 API 变更和文档更新。这两个 API 都可让开发者访问 YouTube 数据分析数据，尽管应用的方式有所不同。订阅此变更日志。

2022 年 12 月 15 日

YouTube 数据分析（定位查询）API 支持两个新维度和一个新报告：

• 新报告按城市提供用户活动。此报告适用于频道和内容所有者。此报告包含新的 city 维度，该维度可标识 YouTube 对发生用户活动的城市所做的推测。

• 新的 creatorContentType 维度用于标识与数据行中的用户活动指标相关联的 YouTube 内容类型。支持的值包括 LIVE_STREAM、SHORTS、STORY 和 VIDEO_ON_DEMAND。

  所有频道和内容所有者视频报告均支持将 creatorContentType 维度用作可选维度。

• YouTube 数据分析 API 请求示例指南现在提供了针对这两个新维度的示例。

• 我们从文档中移除了对 7DayTotals 和 30DayTotals 维度的引用。这些维度已于 2019 年 10 月弃用。

2022 年 8 月 26 日

YouTube Analytics（定位查询）API 和 YouTube 报告（批量报告）API 都支持新的流量来源详细信息值：

• 在 YouTube Analytics API（目标查询）API 中，如果 insightTrafficSourceType 维度的值为 SUBSCRIBER，insightTrafficSourceDetail 的值可以设置为 podcasts，表示流量是从播客目标网页引荐的。
• 在 YouTube 报告（批量报告）API 中，如果 traffic_source_type 维度的值为 3，traffic_source_detail 的值可以设为 podcasts，这表示流量是从播客目标网页引荐的。

2022 年 2 月 11 日

gender 维度的有效值集将于 2022 年 8 月 11 日当天或之后更改。这可能是您的 API 实现不向后兼容的更改。为了符合 YouTube API 服务服务条款的向后不兼容的更改部分，此变更将于 6 个月前生效。请在 2022 年 8 月 11 日之前更新您的 API 实现，以确保顺利过渡到一组新值。

具体更改如下：

• 在 YouTube Analytics（定位）API 中，gender 维度目前支持两个值：female 和 male。自 2022 年 8 月 11 日起，该维度将支持 3 个值：female、male 和 user_specified。
• 在 YouTube 报告（批量报告）API 中，gender 维度目前支持三个值：FEMALE、MALE 和 GENDER_OTHER。 自 2022 年 8 月 11 日起，受支持的值集将更改为 FEMALE、MALE 和 USER_SPECIFIED。

2022 年 2 月 9 日

截至 2021 年 12 月 13 日，已更新两个指标以排除循环播放的剪辑流量。此更改会同时影响 YouTube Analytics（定位）API 和 YouTube Reporting（批量报告）API。

• 在 YouTube Analytics（分析）（目标查询）API 中，自 2021 年 12 月 13 日起，averageViewDuration 和 averageViewPercentage 指标均排除循环剪辑流量。
• 在 YouTube 报告（批量报告）API 中，自 2021 年 12 月 13 日起，average_view_duration_seconds 和 average_view_duration_percentage 指标均排除循环剪辑流量。

2022 年 2 月 2 日

此 YouTube 报告 (Bulk Reports) API 支持新的流量来源维度值，该值可表明观看次数来自直播跳转：

• 在 YouTube 报告（批量报告）API 中，traffic_source_type 维度支持值 28。

对于此流量来源类型，traffic_source_detail 维度指定引荐观看者的渠道 ID。

2020 年 9 月 23 日

此 YouTube Analytics（定位查询）API 和 YouTube 报告（批量报告）API 都支持新的流量来源维度值，用于表明观看者是通过在 YouTube Shorts 观看体验中垂直滑动来引荐的：

• 在 YouTube Analytics API（定位查询）API 中，insightTrafficSourceType 维度支持值 SHORTS。
• 在 YouTube 报告（批量报告）API 中，traffic_source_type 维度支持值 24。

对于这种新的流量来源类型，系统不会填充流量来源详细信息维度（YouTube Analytics API 中的 insightTrafficSourceDetail 或 YouTube Reporting API 中的 traffic_source_detail）。

2020 年 7 月 20 日

本次更新涉及两项会影响 YouTube 数据分析（目标查询）API 的更改：

• YouTube 数据分析报告群组的大小上限已从 200 个实体增加到 500 个。
• reports.query 方法的 filters 参数用于标识在检索 YouTube 数据分析数据时应该应用的过滤条件列表。该参数支持为 video、playlist 和 channel 过滤条件指定多个值，并且可为这些过滤条件指定的 ID 数量上限从 200 个 ID 增加到了 500 个。

2020 年 2 月 13 日

此更新包含与 YouTube 数据分析（目标查询）API 和 YouTube 报告（批量报告）API 相关的以下变更。您可以访问 YouTube 帮助中心，详细了解这些变更。

在这两种 API 中，通知的可能流量来源详细信息值会发生更改。在有针对性的查询中，通知会被报告为 insightTrafficSourceType=NOTIFICATION。在批量报告中，通知会以 traffic_source_type=17 的形式报告。

新值会将与上传的视频和直播（之前报告为 uploaded）相关的通知分为两类：

• uploaded_push - 视频上传后向订阅者发送的推送通知产生的观看次数
• uploaded_other - 视频上传时发送给订阅者的非推送通知（例如电子邮件或收件箱通知）的观看次数。

系统会针对 2020-01-13（2020 年 1 月 13 日）这一时间范围返回这些值。

此外请注意，这些值并不代表通知本身，而是指推动特定 YouTube 观看次数的流量来源。例如，如果报告行指出 views=3、traffic_source_type=17 (NOTIFICATION) 和 traffic_source_detail=uploaded_push，则表示有 3 次观看来自观看者点击上传视频时发送的推送通知。

2019 年 10 月 15 日

本次更新包含与 YouTube Analytics（定位查询）API 相关的以下变更：

• 注意：这是弃用公告。

  YouTube 即将停止支持 7DayTotals 和 30DayTotals 维度。在 2020 年 4 月 15 日之前，您仍然可以使用这些维度检索数据。在该日期当天或之后，尝试使用 7DayTotals 或 30DayTotals 维度检索报告会返回错误。

  请注意，用户可以使用“day”维度进行查询并在 7 天或 30 天内汇总或推导这些维度的数据，来重现这些维度的部分数据。例如：

  • 通过汇总该时间段内每一天的观看次数，即可计算出七天内的观看次数。
  • 用 7 天内的 Viewer Percent 乘以每天的 ViewerPercentage 乘以当天的 ViewerPercentage 所得的值，得出这一天的登录观看者人数。然后，可以将登录观看者人数乘以整个时间段，再除以该时间段内的总观看次数，以便得出整个时间段的查看者百分比。
  • 无法计算七天内的唯一身份观看者人数，因为同一个观看者在不同的日期可能会被计算为唯一身份观看者人数。不过，您或许可以使用 month 维度（而不是 30DayTotals 维度）来推断 30 天内唯一身份观看者人数的相关数据。请注意，month 维度是指日历月，而 30DayTotals 维度是根据指定的开始日期和结束日期计算的 30 天时间段。

2019 年 6 月 27 日

本次更新包含与 YouTube Analytics（定位查询）API 相关的以下变更：

• 由于 API 版本 1 现已完全弃用，本文档已更新，移除了对该版本的引用，包括弃用通知以及说明如何更新到版本 2 的迁移指南。

2018 年 11 月 1 日

本次更新包含与 YouTube Analytics（定位查询）API 相关的以下变更：

• 该 API 的版本 1 现已弃用。如果您尚未更新 API 客户端，请尽快更新以使用 API 版本 2，以尽可能减少服务中断。如需了解详情，请参阅迁移指南。

  请注意，弃用时间表最初于 2018 年 4 月 26 日公布。

2017 年 9 月 17 日

本次更新包含与 YouTube Analytics（定位查询）API 相关的以下变更：

• 数据模型概览文档中新增的数据匿名化部分会指出，当指标未达到特定阈值时，部分 YouTube 数据分析数据将受到限制。这种情况可能会在多种情况下发生。实际上，这意味着在以下情况下，报告可能不会包含您的所有（或任何）数据：

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

     或

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

  新部分中还讨论了 YouTube 数据分析报告中可能会受到限制的数据类型。

• 频道报告和内容所有者报告文档已更新，表明“播放位置”“流量来源”和“设备类型/操作系统”报告不再支持“redViews”和“estimatedRedMinutesWatched”指标。

2018 年 6 月 18 日

本次更新包含对 YouTube Analytics（定位查询）API 的以下更改：

• 以下方法的范围要求已更改：
  • 对 reports.query 方法的请求必须有权访问 https://www.googleapis.com/auth/youtube.readonly 范围。
  • 对 groupItems.list 方法的请求必须具有以下任一权限：
    • https://www.googleapis.com/auth/youtube 范围
      或
    • https://www.googleapis.com/auth/youtube.readonly 范围
      和
      https://www.googleapis.com/auth/yt-analytics.readonly 范围

    第一个选项使用范围，碰巧是读写范围，而第二个选项使用两个只读范围。

2018 年 5 月 23 日

本次更新包含对 YouTube Analytics（定位查询）API 的以下更改：

• “API 概览”中新增了汇总指标和已删除内容部分，其中说明了 API 响应如何处理与已删除资源（例如视频、播放列表或频道）相关的数据。
• “API 概览”的最佳做法部分已更新，提醒您使用 YouTube Data API 可检索在 YouTube 数据分析 API 响应中识别出的资源的其他元数据。如 YouTube API 服务开发者政策（第 III.E.4.b 至 III.E.4.d 节）中所述，API 客户端必须在 30 天后从该 API 中删除或刷新存储的资源元数据。

2018 年 5 月 22 日

本次更新包含与 YouTube Reporting (Bulk Reports) API 相关的以下变更：

• 我们计划于 2018 年 7 月开始实施以下更改，而所有政策及报告作业将在全球范围内应用新政策。

  • 此次变更生效后，大多数 API 报告（包括补余广告报告）自生成之日起 60 天内可用。不过，包含历史数据的报告将在生成之日后保留 30 天。

    在此公告之前，所有 API 报告在生成后的 180 天内有效。需要说明的是，此政策变更生效后，您将无法再通过该 API 获取超过 30 天的历史数据报告。超过 60 天的所有其他报告也将无法再访问。因此，该文档现在指出，在此政策变更之前创建的报告最长可供使用 180 天。

  • 实施这项更改后，当您安排报告作业时，YouTube 会从当天起开始生成报告，并在报告生成之前 30 天内生成报告。在此变更之前，YouTube 会根据您安排的举报时间来生成之前 180 天内的报告，

• 提醒：最佳做法部分已更新，您可以使用 YouTube Data API 为报告中标识的资源检索其他元数据。如 YouTube API 服务开发者政策（第 III.E.4.b 至 III.E.4.d 节）中所述，API 客户端必须在 30 天后从该 API 中删除或刷新存储的资源元数据。

• 我们更新了报告特征部分。请注意，虽然报告数据并没有过滤，但对于 2018 年 6 月 1 日当天或之后一段时间内的报告，报告中不会包含对在报告生成日期前至少 30 天被删除的 YouTube 资源的任何引用。

• API 概览中的历史数据部分现已更新，以方便您安排新报告作业时，历史报告通常会在几天内发布。之前，相关文档指出，此类报告最多可能需要 30 天才会显示。

• 我们更新了 API 概览中的回填数据部分，以便更清楚地将回填数据定义为替换之前投放的数据集。

2018 年 4 月 26 日

第 2 版 YouTube Analytics（定位查询）API (v2) 现已公开发布。以下列表列出了与新版 API 相关的产品和文档变更：

• v2 API 与 v1 API 几乎完全相同。不过，您可能需要更新代码，以反映下面列出的更改。新的迁移指南对所有这些变更进行了详细说明。

  • API 的版本已从 v1 更改为 v2。
  • API 请求的基准网址已从 https://www.googleapis.com/youtube/analytics/v1 更改为 https://youtubeanalytics.googleapis.com/v2。
  • reports.query 方法的多个参数已更新名称。具体而言，包含连字符的参数名称（例如 v1 API 中的 end-date）使用的是驼峰式大小写形式 (endDate)，而不是 v2 API 中的连字符。此更改使整个 API 中的参数名称保持一致，因为该 API 用于创建和管理已经为参数名称使用驼峰式大小写的组的方法。
  • v2 API 不支持发送到 Google 全球 HTTP 批量端点 (www.googleapis.com/batch) 的批量请求。如果要在 v2 API 中发送批量请求，则需要使用端点 https://youtubeanalytics.googleapis.com/v2。

  此外，v2 API 中不支持某些 v1 功能：

  • reports.query 方法不再支持 alt、quotaUser 和 userIp 请求参数。
  • v2 API 不提供支持由针对不同 API 的请求组成的批次的批处理端点。（不过，批量可以包含对同一 API 的不同方法的请求。）弃用此参数并非仅适用于 YouTube Analytics API，因为 Google 即将弃用其所有 API 中的全球批量端点。
  • v2 API 不支持 JSON-RPC 协议，API v1 支持该协议。同样，这次弃用并不仅限于 YouTube 数据分析 API。

• 注意：这是弃用公告。

  API 版本 1 (v1) 现已弃用，但将于 2018 年 10 月 31 日结束。该日期之后，向 v1 API 发出的所有请求都将停止工作。因此，请务必在 2018 年 10 月 31 日之前升级到 v2 API，以免您无法通过 API 访问 YouTube 数据分析数据。

2018 年 2 月 21 日

本次更新包含对 YouTube Analytics（定位查询）API 的以下更改：

• “观看者受众特征”报告（根据观看者的年龄段和性别汇总观看统计信息）不再支持“youtubeProduct”维度（可用于识别发生用户活动的 YouTube 服务）。

2018 年 1 月 18 日

此更新包含以下更改：

• YouTube Reporting API（批量报告）

  • operating_system 维度（标识发生浏览的设备的软件系统）现在支持以下值：
    • 25：KaiOS

• YouTube 数据分析 API（目标查询）

  • operatingSystem 维度支持尺寸值 KAIOS。

2017 年 12 月 20 日

本次更新包含两项与 YouTube Reporting API 相关的变更：

• API 服务器现在支持为下载报告的请求采用 gzip 压缩。请注意，其他类型的 API 请求不支持 gzip 压缩。启用 gzip 压缩可减少每个 API 响应所需的带宽。而且，虽然您的应用需要花费额外的 CPU 时间来解压缩 API 响应，但消耗的网络资源所带来的好处通常大于所消耗的资源。

  如需接收 gzip 编码的响应，请将 Accept-Encoding HTTP 请求标头设置为 gzip，如以下示例所示：

  Accept-Encoding: gzip

  API 概览和 report 资源的 downloadUrl 属性定义对此功能进行了说明。

• 更正了 age group 和 gender 维度的文档，以显示 API 针对这些维度返回的实际值。请注意，这是文档更正，并未反映 API 功能或行为的变化。具体来说，以下值已发生更改：

  • age_group 维度的值使用大写字母，在单词 AGE 和年龄段中的数字之间使用下划线，并使用下划线而不是连字符。因此，age13-17 和 age18-24 等值已分别更正为 AGE_13_17 和 AGE_18_24。
  • gender 维度的值使用大写字母。因此，值 female、male 和 gender_other 已更正为 FEMALE、MALE 和 GENDER_OTHER。

2017 年 8 月 10 日

2016 年 8 月 10 日，本文档宣布了弃用 YouTube Analytics API 的 earnings 指标。（同时，该 API 添加了对名为 estimatedRevenue 的新指标的支持，该指标可提供相同的数据。）

由于 earnings 指标是核心指标，因此自公告日期起的一年内一直受支持。不过，现在这一整年都已结束，earnings 指标不再受支持。因此，指定 earnings 指标的 API 请求现在会返回 400 HTTP 响应代码。如果您尚未将应用更新为使用 estimatedRevenue 指标（而非 earnings 指标），请尽快进行更新。

API 文档已更新，移除了对 earnings 指标的剩余引用。

2017 年 7 月 6 日

此更新包含以下更改：

• YouTube 数据分析 API（目标查询）

  • API 文档已更新，以反映 API 响应包含截至所请求日期范围内最后一天的所有数据可供查询的数据。

    例如，如果请求指定的结束日期为 2017 年 7 月 5 日，并且所有请求的指标的值仅在 2017 年 7 月 3 日之前可用，则该日期将成为响应中包含数据的最后一个日期。（即使所请求某些指标的数据适用于 2017 年 7 月 4 日也是如此。）

  • adType 维度现在支持值 reservedBumperInstream，该值表示最长 6 秒的不可跳过视频广告，在观看视频之前播放。这种广告格式与auctionBumperInstream广告完全相同，但这种类型的广告是指以预订而不是竞价的方式销售的广告。

• YouTube Reporting API（批量报告）

  • ad_type 维度现在支持 20 值，后者指的是以预订方式出售的导视广告。导视广告是一种时长不超过 6 秒的不可跳过视频广告，在用户观看视频之前播放。请注意，此维度的值 19 还指以竞价而非预订的方式出售的导视广告。

  • 已删除以下 YouTube Reporting API 报告的报告作业：

    • channel_basic_a1
    • channel_province_a1
    • channel_playback_location_a1
    • channel_traffic_source_a1
    • channel_device_os_a1
    • channel_subtitles_a1
    • channel_combined_a1
    • content_owner_basic_a2
    • content_owner_province_a1
    • content_owner_playback_location_a1
    • content_owner_traffic_source_a1
    • content_owner_device_os_a1
    • content_owner_subtitles_a1
    • content_owner_combined_a1
    • content_owner_asset_basic_a1
    • content_owner_asset_province_a1
    • content_owner_asset_playback_location_a1
    • content_owner_asset_traffic_source_a1
    • content_owner_asset_device_os_a1
    • content_owner_asset_combined_a1

    这些报告类型已在 2016 年 9 月 15 日宣布弃用，2016 年 12 月 15 日之后将不再为这些报告类型生成报告。以前生成的报表在生成后的 180 天内仍然有效。因此，部分报告最早可追溯到 2017 年 6 月 15 日。不过，由于这些报表不再可用，因此也不再需要与这些报表关联的作业。

2017 年 5 月 24 日

已删除以下 YouTube Reporting API 报告的所有报告作业：

• content_owner_ad_performance_a1
• content_owner_asset_estimated_earnings_a1
• content_owner_estimated_earnings_a1

我们已于 2016 年 6 月 22 日宣布弃用这些报告类型，并于 2016 年 9 月 22 日之后停止为这些报告类型生成报告。以前生成的报表在生成后的 180 天内仍然有效。因此，某些报告最早可追溯到 2017 年 3 月 22 日。不过，由于这些报表不再可用，因此也不再需要与这些报表关联的作业。

2017 年 5 月 22 日

此更新包含以下更改：

• YouTube Reporting API（批量报告）

  • sharing_service 维度用于标识用于分享视频的服务，现在支持以下值：
    • 85：YouTube Music
    • 86：YouTube 游戏
    • 87：YouTube Kids
    • 88：YouTube TV

    此外，为了标识值“52”这一名称，文档中已更新为 Kakao (Kakao Talk)，以便更明确地将其与值 73（Kakao 故事）区分开来。此变更不会反映与这些服务共享的视频在 API 行为或分类方面的任何变化。

• YouTube 数据分析 API（目标查询）

  • sharingService 维度现在支持以下值：
    • YOUTUBE_GAMING
    • YOUTUBE_KIDS
    • YOUTUBE_MUSIC
    • YOUTUBE_TV

2017 年 3 月 28 日

现在可以在创作者工作室中通过 YouTube 数据分析访问收入数据的频道所有者现在也可以通过 YouTube 数据分析 API 访问这些收入数据：

• 该 API 支持以下与收入相关的指标：

  • adImpressions
  • cpm
  • estimatedAdRevenue
  • estimatedRedPartnerRevenue
  • estimatedRevenue
  • grossRevenue
  • monetizedPlaybacks
  • playbackBasedCpm

  以下报告支持这些指标：

  • 基本用户活动统计信息
  • 特定时间段内用户所在国家/地区的活动
  • 用户活动（按国家/地区划分）
  • 具有可选地区性过滤条件的热门视频

• 现在，频道所有者还可以检索广告效果报告，该报告支持 adType 维度以及可选的 day 维度。

• YouTube 数据分析 API 请求示例指南现在包含频道收入报告部分。

2017 年 3 月 17 日

此更新包含以下更改：

• YouTube 数据分析 API 支持 redViews 和 estimatedRedMinutesWatched 指标，这些指标都与 YouTube Red 观看人数有关。实际上，该 API 实际上已经支持这些指标一段时间，YouTube 报告 API 也就已经支持 2016 年 9 月 15 日公布的这两项指标。

  • redViews 指标用于标识视频被 YouTube Red 会员观看的次数。
  • estimatedRedMinutesWatched 指标用于标识 YouTube Red 会员观看视频的分钟数。

  我们更新了频道报告和内容所有者报告文档，以显示哪些报告支持这两个新指标。任何支持 views 和 estimatedMinutesWatched 指标的报告中都支持这类指标。

2017 年 3 月 3 日

此更新包含以下更改：

• YouTube Reporting API（批量报告）

  • 更正了 date 维度的定义，以指明该维度值是指从太平洋时间零点开始，到特定日期、月份和年份晚上 11:59 的时间段。按照一年中的时间，太平洋时间可以是 UTC-7 或 UTC-8。

    虽然日期通常代表 24 小时，但向前调整时钟的日期代表 23 小时，而向后调整时钟的日期则表示 25 小时。（之前的文档指出，每个日期代表唯一的 24 小时时间段，并且太平洋时间始终为 UTC-8。）

    请注意，此更正并不代表实际 API 行为的变化。

  • operating_system 维度（标识发生视图的设备的软件系统）现在支持以下值：
    • 22：Tenzen
    • 23：Firefox
    • 24：RealMedia

  • 已删除“content_owner_basic_a1”报表类型的所有报表作业。该报告类型自 2016 年 8 月 19 日起已被完全弃用，但先前生成的 content_owner_basic_a1 报告在生成后的 180 天内仍然有效。因此，某些报告最早可追溯到 2017 年 2 月 19 日。不过，由于这些报表不再可用，因此也不再需要与这些报表关联的作业。

• YouTube 数据分析 API（目标查询）

  • 与 time periods 相关维度的说明已更正，请注意，维度值是指从凌晨 0:00 太平洋时间开始，到指定日期、月份和年份晚上 11:59（太平洋时间）结束的时间段。按照一年中的时间，太平洋时间可以是 UTC-7 或 UTC-8。

    虽然日期通常代表 24 小时，但向前调整时钟的日期代表 23 小时，而向后调整时钟的日期则表示 25 小时。（之前的文档指出，太平洋时间是 UTC-8，并且没有提到一天可能没有表示 24 小时制。）

    请注意，此更正并不代表实际 API 行为的变化。

  • 渠道报告文档已更新，以指出渠道报告目前不包含收入或广告效果指标。因此，https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围目前不授予对频道报告中的货币数据的访问权限。

  • operatingSystem 维度支持三个新的维度值：
    • FIREFOX
    • REALMEDIA
    • TIZEN

2017 年 2 月 8 日

YouTube 数据分析 API 现在支持可选的 include-historical-channel-data 参数。请注意，此参数仅在检索内容所有者报告时才相关。

此参数让内容所有者可以指明 API 响应应包含频道的观看时间，以及频道与内容所有者相关联的时间之前的数据。默认参数值为 false，这意味着默认情况下，该 API 响应仅包含频道与内容所有者关联之后的观看时长和观看次数数据。

如果 API 请求检索多个渠道的数据，则这些规则也适用：

• 如果参数值为 false，那么系统针对任何特定频道返回的观看时长和观看次数数据都是基于该频道与内容所有者相关联的日期。
  
  请务必注意，不同的频道可能已在不同的日期与内容所有者进行了关联。如果 API 请求要检索多个频道的数据，而参数值为 false，那么 API 响应会包含基于各个频道关联日期的观看时长和观看数据。
• 如果参数值为 true，则响应会根据 API 请求中指定的开始日期和结束日期返回所有频道的观看时长和观看次数数据。

2016 年 12 月 15 日

以下 YouTube Reporting API 报告已不再受支持，并已从文档中移除。各报告都有更高版本。（这些报告的弃用公告已于 2016 年 9 月 15 日发布）。

• 渠道报告

  • channel_basic_a1 - 已替换为 channel_basic_a2 报告。
  • channel_province_a1 - 已替换为 channel_province_a2 报告。
  • channel_playback_location_a1 - 已替换为 channel_playback_location_a2 报告。
  • channel_traffic_source_a1 - 已替换为 channel_traffic_source_a2 报告。
  • channel_device_os_a1 - 已替换为 channel_device_os_a2 报告。
  • channel_subtitles_a1 - 已替换为 channel_subtitles_a2 报告。
  • channel_combined_a1 - 已替换为 channel_combined_a2 报告。

• 内容所有者报告

  • content_owner_basic_a2 - 已替换为 content_owner_basic_a3 报告。
  • content_owner_province_a1 - 已替换为 content_owner_province_a2 报告。
  • content_owner_playback_location_a1 - 已替换为 content_owner_playback_location_a2 报告。
  • content_owner_traffic_source_a1 - 已替换为 content_owner_traffic_source_a2 报告。
  • content_owner_device_os_a1 - 已替换为 content_owner_device_os_a2 报告。
  • content_owner_subtitles_a1 - 已替换为 content_owner_subtitles_a2 报告。
  • content_owner_combined_a1 - 已替换为 content_owner_combined_a2 报告。
  • content_owner_asset_basic_a1 - 已替换为 content_owner_asset_basic_a2 报告。
  • content_owner_asset_province_a1 - 已替换为 content_owner_asset_province_a2 报告。
  • content_owner_asset_playback_location_a1 - 已替换为 content_owner_asset_playback_location_a2 报告。
  • content_owner_asset_traffic_source_a1 - 已替换为 content_owner_asset_traffic_source_a2 报告。
  • content_owner_asset_device_os_a1 - 已替换为 content_owner_asset_device_os_a2 报告。
  • content_owner_asset_combined_a1 - 已替换为 content_owner_asset_combined_a2 报告。

还更新了 API 参考文档中的当前报告类型列表。

2016 年 11 月 11 日

此更新包含以下更改：

YouTube Reporting API 支持三种新的片尾画面报告，以及这些报告的新维度和指标。这些报告提供的是视频停止播放后显示的片尾画面的展示次数和点击次数统计信息。

• 片尾画面报告

  • 频道视频的片尾画面报告包含关于某个频道所有视频的统计信息。
  • 内容所有者视频的片尾画面报告包含任何内容所有者频道中视频的统计信息。
  • 内容所有者资源的片尾画面报告包含与在视频结束播放后显示的视频相关的素材资源的统计信息。

• 片尾画面尺寸

  • end_screen_element_type：与统计信息关联的片尾画面元素的类型。
  • end_screen_element_id：YouTube 用于唯一标识片尾画面元素的 ID。

• 片尾画面指标

  注意：系统自 2016 年 5 月 1 日起提供片尾画面指标数据。

  • end_screen_element_impressions：片尾画面元素的总展示次数。系统会针对显示的每个片尾画面元素记录一次展示。
  • end_screen_element_clicks：片尾画面元素被点击的次数。
  • end_screen_element_click_rate：片尾画面元素的点击率。

YouTube 帮助中心包含有关向视频添加片尾画面的更多详细信息。

• 以下报告已不再受支持，已从文档中移除。各报告都有更高版本。（这些报告的弃用公告已于 2016 年 6 月 22 日发布）。

  • content_owner_ad_performance_a1 - 已替换为 content_owner_ad_rates_a1 报告。
  • content_owner_estimated_earnings_a1 - 已替换为 content_owner_estimated_revenue_a1 报告。
  • content_owner_asset_estimated_earnings_a1 - 已替换为 content_owner_asset_estimated_revenue_a1 报告。

2016 年 11 月 8 日

此更新包含对 YouTube 数据分析 API 的以下更改：

• 以下列表中的指标已完全弃用，不再受支持。如 2016 年 8 月 10 日所宣布的那样，系统已支持引用相同数据的新指标。下表显示了已弃用的指标名称和新指标名称：

  已弃用的指标	新指标
  adEarnings	estimatedAdRevenue
  impressionBasedCpm	cpm
  impressions	adImpressions
  redPartnerRevenue	estimatedRedPartnerRevenue

2016 年 10 月 27 日

现在，对于有权访问 YouTube 创作者工作室报告部分中相应报告的内容所有者，YouTube 会自动生成一组由系统管理的广告收入报告。新的由系统管理的 API 报告旨在让您以程序化方式访问数据，但您也可以在可手动下载的创作者工作室报告中查看。

系统管理的报告概览提供了新报告的简要概览，并说明了通过 API 检索报告的过程。此过程与为 YouTube 数据分析检索批量报告的过程略有不同，因为合作伙伴无需安排作业即可生成报告。

reportType 资源的 id 属性已更新，现在包含可通过 API 访问的系统管理报告的列表：

• 每个视频的每月全球广告收入
• 各个国家/地区的每日广告收入
• 每月全球每种资产的广告收入
• 各个国家/地区的每日广告收入
• 版权主张（此报告不包含收入数据）

2016 年 9 月 27 日

注意：这是弃用公告。

YouTube 数据分析 API 的 uniques 指标已弃用。这不是核心指标，直到 2016 年 10 月 31 日才会受到支持。

2016 年 9 月 15 日

本次更新包含以下 YouTube Reporting API 变更：

• 该 API 支持两个与 YouTube Red 观看人数相关的新指标：

  • red_views：视频被 YouTube Red 会员观看的次数。
  • red_watch_time_minutes：YouTube Red 会员观看视频的分钟数。

• 该 API 支持 20 个新版本的报告。所有新版本都支持新的 red_views 和 red_watch_time_minutes 指标。

  对于每个报表，新报表类型 ID 中的数字要比旧报表类型 ID 中的数字高 1。（这些报告的旧版本现已弃用，如本修订历史记录后面部分所述。）例如，channel_basic_a1 报告现已弃用，取而代之的是 channel_basic_a2 报告。

  以下列表列出了新的报告类型 ID：

  • 频道视频报告

    • channel_basic_a2
    • channel_province_a2
    • channel_playback_location_a2
    • channel_traffic_source_a2
    • channel_device_os_a2
    • channel_subtitles_a2
    • channel_combined_a2

  • 内容所有者视频报告

    • content_owner_basic_a3
    • content_owner_province_a2
    • content_owner_playback_location_a2
    • content_owner_traffic_source_a2
    • content_owner_device_os_a2
    • content_owner_subtitles_a2
    • content_owner_combined_a2

  • 内容所有者资产报告

    • content_owner_asset_basic_a2
    • content_owner_asset_province_a2
    • content_owner_asset_playback_location_a2
    • content_owner_asset_traffic_source_a2
    • content_owner_asset_device_os_a2
    • content_owner_asset_combined_a2

• 注意：这是弃用公告。

  请注意，如果您已经有创建上文所列任一旧版报告的作业，则需要为重命名的报告创建新的作业。随着新报告版本的发布，以下报告版本已被弃用：

  • channel_basic_a1
  • channel_province_a1
  • channel_playback_location_a1
  • channel_traffic_source_a1
  • channel_device_os_a1
  • channel_subtitles_a1
  • channel_combined_a1
  • content_owner_basic_a2
  • content_owner_province_a1
  • content_owner_playback_location_a1
  • content_owner_traffic_source_a1
  • content_owner_device_os_a1
  • content_owner_subtitles_a1
  • content_owner_combined_a1
  • content_owner_asset_basic_a1
  • content_owner_asset_province_a1
  • content_owner_asset_playback_location_a1
  • content_owner_asset_traffic_source_a1
  • content_owner_asset_device_os_a1
  • content_owner_asset_combined_a1

  如果有任何此类工作的报告，YouTube 不应在 2016 年 12 月 15 日后再生成这些报告。生成的报表在生成后的 180 天内仍可使用。

2016 年 8 月 19 日

本次更新包含以下 YouTube Reporting API 变更：

• content_owner_basic_a1 报告已被完全弃用，并已从文档中移除。YouTube 不会再生成该类型的新报告，但已生成的报告在生成后的 180 天内仍然可用。

  我们已替换 content_owner_basic_a1 报告，后者是 2016 年 5 月 19 日的修订历史记录条目中所述的 content_owner_basic_a2 报告。

2016 年 8 月 11 日

此更新包含以下更改：

• 新发布的 YouTube API 服务的《服务条款》（以下简称“更新版条款”）在 YouTube 工程和开发者博客中进行了详细讨论，其中提供了丰富的现行服务条款更新。除了更新条款（将于 2017 年 2 月 10 日生效）之外，此更新还包含一些辅助文档，这些文档有助于阐明开发者必须遵守的政策。

  如需了解整套新文档，请参阅新版条款的修订历史记录。此外，修订后的条款或支持文档日后的修订也会反映在修订历史记录中。您可以通过该文档中的链接订阅该修订版本历史记录中的 RSS Feed 更改。

2016 年 8 月 10 日

本次更新包含以下更改：

• YouTube 数据分析 API（目标查询）

  • 注意：这是弃用公告。

    下表中的指标即将弃用。同时，还将引入引用相同数据的新指标。实际上，这意味着 Google Analytics（分析）API 将同时支持这两种指标名称，直到下表中列出的弃用日期为止。

    旧指标名称	新指标名称	支持日期
    earnings	estimatedRevenue	2017 年 8 月 10 日
    adEarnings	estimatedAdRevenue	2016 年 11 月 4 日
    redPartnerRevenue	estimatedRedPartnerRevenue	2016 年 11 月 4 日
    impressionBasedCpm	cpm	2016 年 11 月 4 日
    impressions	adImpressions	2016 年 11 月 4 日

    请注意，earnings 指标是一个核心指标，因此自本公告发布之日起一年内仍将受支持。其他核心指标在 2016 年 11 月 4 日之前仍可使用 3 个月。

    例如，在 2016 年 11 月 4 日之前，API 请求可以指定 impressionBasedCpm 指标和/或 cpm 指标。不过，该日期之后，仅支持 cpm 指标。

  • insightTrafficSourceType 维度支持两种新的维度值：
    • CAMPAIGN_CARD：此流量来源仅适用于内容所有者报告。这表示观看次数源自用户上传的、由内容所有者用来宣传所观看内容的已声明视频。
    • END_SCREEN：数据与其他视频片尾画面中的观看次数有关。

    对于这两种新的流量来源，您还可以检索traffic source detail报告。在这两种情况下，insightTrafficSourceDetail 维度均标识出由观看者引荐的视频。

  • adType 维度现在支持值 auctionBumperInstream，该值表示最长 6 秒的不可跳过视频广告，在观看视频之前播放。

• YouTube Reporting API（批量报告）

  • traffic_source_type 维度现在支持以下值：
    • 19：此流量来源仅适用于内容所有者报告。这表示观看次数源自用户上传的、由内容所有者用来宣传所观看内容的已声明视频。
    • 20：数据与其他视频片尾画面中的观看次数有关。

    对于这两个新流量来源，traffic_source_detail 维度标识出观看者被引荐到的视频。

  • 更正了 API 的核心指标列表，将 estimated_partner_revenue 列为核心指标，并从列表中移除 earnings。（YouTube Reporting API 从不支持 earnings 指标）。

  • ad_type 维度现在支持的值 19 是指导视广告，这是一种时长不超过 6 秒的不可跳过的视频广告，需要在用户观看视频前播放。

2016 年 7 月 18 日

本次更新包含以下更改：

• YouTube 数据分析 API（目标查询）

  • 我们更新了下列渠道报告支持的指标列表，以包含卡片指标。这些报告中的卡片指标实际上是在 2016 年 6 月 28 日添加的，当天的修订历史记录条目更详细地介绍了这一变化。报告如下：
    • 美国各州的基本用户活动
    • 美国用户在特定时间段内的活动
    • 用户活动（按省份）
    • 用户活动（按订阅状态）
    • 用户活动（按省份划分）状态
    • 各州的热门视频
    • 已订阅或未订阅的观看者人数最多的视频

  • 系统已更正频道观众黏度报告和内容所有者观众黏度报告的过滤条件列表，以反映 video 过滤条件是必需的，group 过滤条件不受支持。

    之前，这两个报表的文档错误地指出可以使用这两个过滤条件中的一个来检索报表。

• YouTube Reporting API（批量报告）

  • 在 API 概览中，介绍如何检索报告的下载网址部分已更正，指出 YouTube 会在无可用数据的日期生成可下载的报告。这些报告包含一个标题行，但不包含其他数据。此信息已于 2016 年 4 月 12 日在同一文档的报告特征部分更新。
  • “content_owner_asset_cards_a1”报告中的维度列表已得到更正，以反映此报告使用“card_id”维度。以前，这类文档错误地将维度名称列为 card_title。

2016 年 6 月 28 日

YouTube Analytics（分析）API 文档已更新，以在许多频道报告和内容所有者报告中反映对卡片指标的支持。新支持的指标包括：

• cardImpressions
• cardTeaserImpressions
• cardClicks
• cardTeaserClicks
• cardClickRate
• cardTeaserClickRate

以下类型的报告支持这些指标：

• 基本统计信息（频道、内容所有者）
• 基于时间（频道、内容所有者）
• 用户地理位置（频道、内容所有者）
• 按订阅状态划分的用户活动（频道、内容所有者）
• 热门视频（频道、内容所有者）

2016 年 6 月 22 日

本次更新包含以下 YouTube Reporting API 变更。第一项更改通常与该 API 相关，其余更改只会影响内容所有者报告：

• “API 概览”中的报告特征部分已更新，阐明了报告生成后的 180 天内可以通过 API 获得报告。

  之前，本文档指出，在发送 API 请求之日前，最多可提供 180 天的报告。虽然从技术层面来讲，原始文字也确实比较理想，但相当令人困惑。

• 该 API 支持新版本的三种报告。其中两种报告还包含新的和已重命名的指标：

  • content_owner_ad_rates_a1 报告是新版本的 content_owner_ad_performance_a1 报告。新重命名的报告与以前的版本相同。

  • 重命名了两个版本的报告：

    • 新版content_owner_estimated_earnings_a1报告名为 content_owner_estimated_revenue_a1。
    • 新版content_owner_asset_estimated_earnings_a1报告名为 content_owner_asset_estimated_revenue_a1。

    新重命名的这两个报告都与先前报告的不同之处如下：

    • 他们添加了新的estimated_partner_red_revenue指标，该指标可估算 YouTube Red 订阅带来的总收入。
    • 他们添加了新的estimated_partner_transaction_revenue指标，该指标可估算付费内容和粉丝资助等交易产生的收入（扣除合作伙伴收取的退款后的金额）。
    • 他们将 estimated_partner_ad_sense_revenue 指标重命名为 estimated_partner_ad_auction_revenue。
    • 他们将 estimated_partner_double_click_revenue 指标重命名为 estimated_partner_ad_reserved_revenue。

  请注意，如果您已经有创建这些旧版报告的作业，则需要为重命名的报告创建新的作业。随着新报告版本的发布，content_owner_ad_performance_a1、content_owner_estimated_earnings_a1 和 content_owner_asset_estimated_earnings_a1 报告已被弃用。

  如果您在这些报告中拥有任何任务，YouTube 不应再在 2016 年 9 月 22 日之后为这些任务生成新的报告。生成的报表在生成后的 180 天内仍可使用。

• 更新了 reportType 资源的 id 属性的定义，以反映当前可用的报告集。

• 文档中两个指标的名称已得到更正，与报告中显示的名称一致。这只是一份文档修复，不会反映实际报告内容的变化：

  • estimated_partner_adsense_revenue 指标的名称已更新为 estimated_partner_ad_sense_revenue。但请注意，该指标只会显示在此次更新中弃用的 2 个报告中。如上所述，在此类较新版本的报表中，此指标已重命名为 estimated_partner_ad_auction_revenue。
  • estimated_partner_doubleclick_revenue 指标的名称已更新为 estimated_partner_double_click_revenue。同样，请注意，只有此次更新中弃用的两份报告才会显示该指标。如上所述，在此类较新版本的报表中，此指标已重命名为 estimated_partner_ad_reserved_revenue。

• Reporting API 的维度文档已更新，不再列出 elapsed_video_time_percentage 和 audience_retention_type 属性。通过 API 获取的任何报告目前不支持这些维度。

2016 年 5 月 19 日

本次更新包含以下 YouTube Reporting API 变更：

• 该 API 支持针对内容所有者的用户活动报告的新版本。新报表的类型 ID 是 content_owner_basic_a2。与之前的报告版本 content_owner_basic_a1 不同，新版本支持 likes 和 dislikes 指标。

  如果您已经有任务来创建“content_owner_basic_a1”报告，则仍需为“content_owner_basic_a2”报告创建新任务。YouTube 不会自动将内容所有者迁移到新报告版本，也不会自动创建作业来生成新报告版本。在某些实现中，新意外作业的出现可能是重大更改。

  随着新报告的发布，content_owner_basic_a1 报告已被弃用。如果您拥有相关报告的职位，YouTube 将不会在 2016 年 8 月 19 日之后为该职位生成新报告。生成的报表在生成后的 180 天内仍可使用。

• reportType、job 和 report 资源都支持用新属性来标识关联的资源是否表示已废弃的报告类型：

  • reportType 资源的 deprecateTime 属性用于指定报告类型将被弃用的日期和时间。该资源仅含有已宣布弃用的报告的值，该值表示 YouTube 停止生成相应类型报告的日期。

    某个报告类型被宣布为“已弃用”后，YouTube 会再生成 3 个月的报告。例如，2016 年 5 月 19 日进行的这项更新宣布弃用“content_owner_basic_a1”报告。因此，该报表类型的 deprecateTime 会指定 2016 年 8 月 19 日那段时间，之后 YouTube 将停止生成该类型的报表。

  • job 资源的 expireTime 属性用于指定作业到期或到期的日期和时间。如果与作业关联的报告类型已弃用，或为该作业生成的报告长时间未下载，此属性的值会是相应的。该日期表示 YouTube 不再为此职位生成新报告的时间。

  • report 资源的 jobExpireTime 属性用于指定与报告关联的作业过期或到期的日期和时间。此属性包含的值与 job 资源中的 expireTime 属性相同，如本列表的上一项所述。

• 现在，如果您尝试为已弃用的报告创建作业，jobs.create 方法会返回 400 HTTP 响应代码 (Bad Request)。此外，该方法的文档现在还列出了导致 API 请求失败的其他一些原因。

2016 年 4 月 12 日

此更新包含以下变更，所有变更只会影响 YouTube Reporting API：

• 现在，YouTube 会生成在首次安排报告作业之前 180 天内的数据。以前，Reporting API 不提供任何历史数据。此更改会影响所有作业，包括在此公告之前创建的作业。

  历史报告会在提供后立即发布，但作业的所有历史数据大约需要一个月时间才能发布。因此，在安排报告作业一个月后，您可以访问大约七个月的数据。（与本公告发布之前创建的任务有关的所有历史数据应该会在公布后的一个月内发布）。

  请注意，历史数据仅适用于 2015 年 7 月 1 日的数据。因此，2015 年 12 月 28 日之前创建的招聘信息的历史数据将少于 180 天。

  Reporting API 概览中的新历史数据部分对这些更改做出了说明。

• 更新了 YouTube Reporting API 概览的报告特征部分，并做出了以下更改：

  • 本文档现在指出，报告生成后的期限为 180 天，因此可供 API 客户端下载。此前，本文档指出，在发送 API 请求之前，报告最多可保留六个月。

  • 本文档已更新，以反映这一 API 现在为没有可用数据的日期生成可下载的报告这一事实。这些报告将包含标题行，但不包含其他数据。

• YouTube Reporting API 即将支持一组由系统自动生成的报告，这些报告中包含广告收入数据或 YouTube Red 订阅收入数据。内容所有者将能够在 YouTube 创作者工作室中访问手动下载的收入报告。因此，新的 API 功能将能够以编程方式访问这些数据。

  我们现在宣布了下列 API 变更，以便为发布系统管理的报告做好准备：

  • job 资源的新 systemManaged 属性用于指明该资源是否描述了生成系统管理报告的作业。YouTube 会自动为 YouTube 内容所有者生成系统管理的报告，但内容所有者无法修改或删除创建这些报告的作业。

  • jobs.list 方法的新 includeSystemManaged 参数用于指明 API 响应是否应包含系统管理的报告的作业。该参数的默认值为 false。

  • jobs.reports.list 方法的新 startTimeAtOrAfter 参数表示，仅当报告中的最早数据不早于指定日期时，API 响应才应包含报告。同样，startTimeBefore 参数表示仅当报告中的最早数据早于指定日期时，API 响应才应包含报告。

    该方法的 createdAfter 参数与报告创建时间不同，新参数则与报告中的数据相关。

  • reportType 资源的新 systemManaged 属性用于指明该资源是否描述系统管理的报告。

  • reportTypes.list 方法的新 includeSystemManaged 参数用于指明 API 响应是否应包含系统管理的报告。该参数的默认值为 false。

2016 年 3 月 28 日

YouTube Reporting API 和 YouTube Analytics API 现在可返回一些其他分享服务的观看统计信息。

• 在 YouTube Reporting API 中，sharing_service 维度支持以下新值：
  • 82：iOS 系统活动对话框
  • 83：Google 收件箱
  • 84：Android Messenger
• 在 YouTube Analytics API 中，sharingService 维度支持以下新值：
  • ANDROID_MESSENGER：Android Messenger
  • INBOX：Google 收件箱
  • IOS_SYSTEM_ACTIVITY_DIALOG：iOS 系统活动对话框

2016 年 3 月 16 日

此更新包含以下更改，这些更改会同时影响 YouTube Reporting API 和 YouTube Analytics API：

YouTube Reporting API

• playback_location_type 维度支持两种新的维度值：
  • 7：此数据涉及在 YouTube 首页或主屏幕上、用户的“订阅内容”动态或其他 YouTube 浏览功能中产生的观看次数。
  • 8：这类数据与直接在 YouTube 搜索结果页上产生的观看次数有关。
• traffic_source_type 维度现在支持将 18 用作维度值。此值表示视频观看次数来自列出播放列表中的所有视频的页面。此来源与来源类型 14 不同，来源类型表示视频在播放列表播放期间产生的观看次数。

YouTube 数据分析 API

• insightPlaybackLocationType 维度支持两种新的维度值：
  • BROWSE：此数据涉及在 YouTube 首页或主屏幕上、用户的“订阅内容”动态或其他 YouTube 浏览功能中产生的观看次数。
  • SEARCH：这类数据与直接在 YouTube 搜索结果页上产生的观看次数有关。
• insightTrafficSourceType 维度现在支持将 YT_PLAYLIST_PAGE 用作维度值。此值表示视频观看次数来自列出播放列表中的所有视频的页面。此来源与 PLAYLIST 来源类型不同，来源类型表示视频在播放列表播放期间产生的观看次数。

2016 年 2 月 8 日

YouTube Analytics API 支持的指标列表已更新，因此卡片指标不再列为该 API 支持的指标。（该 API 的报告均未被记录为支持任何卡片指标。）

请注意，您仍然可以使用 YouTube Reporting API 检索卡片指标，该 API 支持为多种频道报告和内容所有者报告使用这些指标。

2016 年 1 月 6 日

现在，YouTube Reporting API 和 YouTube Analytics API 都可以明确识别通过 Chromecast 设备产生的观看次数。

• 在 YouTube Reporting API 中，operating_system 维度使用值 21 来标识通过 Chromecast 产生的观看次数，
• 在 YouTube Analytics API 中，operatingSystem 维度使用值 CHROMECAST 来标识通过 Chromecast 产生的观看次数，

2015 年 12 月 21 日

在本文档中，annotation_clickable_impressions 和 annotation_closable_impressions 指标的名称已更新，以与报告返回的名称保持一致。以前，相关名称以 clickable_annotation_impressions 和 closable_annotation_impressions 的形式记录。

2015 年 12 月 18 日

根据欧盟 (EU) 法律，您必须向欧盟境内的最终用户提供某些披露信息并获得用户的同意。因此，对于欧盟境内的最终用户，您必须遵守欧盟地区用户意见征求政策。我们在 YouTube API 服务条款中添加了关于此要求的通知。

2015 年 12 月 15 日

此更新包含以下更改，所有这些更改都会影响 YouTube Analytics API：

• YouTube Analytics API 现在支持三个新的播放详情维度，这些维度可用于各种频道和内容所有者报告中：

  • liveOrOnDemand：此维度表示报告中的数据是否描述了直播期间发生的用户活动。
  • subscribedStatus：此维度表示数据中的用户活动指标是否与订阅视频或播放列表频道的观看者相关联。
  • youtubeProduct：此维度可标识发生用户活动的 YouTube 媒体资源。可能的值包括核心 YouTube 网站（或 YouTube 应用）、YouTube Gaming 和 YouTube Kids。

  我们更新了文档，以标识适合频道和内容所有者的全新播放详情报告。此外，许多其他报告也进行了更新，以指明其中的一个或多个维度可用作这些报告中的维度和/或过滤条件。

• 为便于解读报告，我们更改了报告说明的表格格式，以方便您识别可用于检索各个报告的维度、指标和过滤器组合。下表介绍了各种渠道的“设备类型”报告，其中展示了新格式：

  目录
  尺寸：	必需 设备类型 使用 0 个或更多 day、liveOrOnDemand、subscribedStatus、youtubeProduct
  指标：	使用 1 个或更多 观看次数、estimatedMinutesWatched
  过滤器：	使用 0 或 1 country、省、洲、次大陆 使用 0 或 1 video、group 使用 0 个或更多 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

  渠道报告和内容所有者报告的相关文档说明了必填字段和可选字段。

• 现在，YouTube Analytics API 会自动删除 API 用户无法从支持多个值的过滤器（video、playlist 和 channel）中检索数据的实体。之前，如果 API 用户无法访问至少一个指定项的数据，API 服务器就会返回错误。

  例如，假设用户提交的 API 请求由 video 过滤条件列出 20 个视频 ID。该用户拥有 18 个视频。但是，一个视频 ID 用于标识归其他频道所有的视频，而另一个 ID 则标识已被删除的视频，因此已被删除。在这种情况下，API 服务器不会返回错误，而是丢弃用户无法访问的两个视频，并且 API 响应会包含该 API 用户拥有的 18 个视频的数据。

• 如果您请求 YouTube 数据分析 group 为空，则 API 现在会返回空数据集而不是错误。

• 现在，如果您尝试将某个实体添加到群组，但无权访问该实体，YouTube Analytics API 的 groupItems.insert 方法会返回一个未经授权的（403 HTTP 响应代码）错误。以前，该 API 会允许您将实体添加到组，但之后在尝试检索该组的报告数据时，会返回未经授权的错误。

• YouTube Analytics API 的 groups.list 方法现在支持分页。如果 API 响应未包含所有可用群组，则响应的 nextPageToken 参数会指定可用于检索下一页结果的令牌。将该方法的 pageToken 参数设置为该值，以检索更多结果。

2015 年 11 月 10 日

此更新包含以下更改：

• YouTube Analytics API 现在支持 redPartnerRevenue 指标，该指标可报告所选报告维度从 YouTube Red 订阅中获得的总估算收入。该指标的值反映了通过音乐和非音乐内容获得的收入，并且可能在月末进行调整。

  YouTube 数据分析 API 的内容所有者报告列表已更新，可标识支持 redPartnerRevenue 指标的视频报告：

  • 基本统计信息
  • 基于时间
  • 用户地理位置
  • 热门视频 - 此报告还支持redPartnerRevenue作为排序指标，这意味着您可以检索按 YouTube Red 收入排序的视频列表。

• YouTube 数据分析 API 的热门视频报告定义现已反映，此报告还支持以下收入指标：earnings、adEarnings、grossRevenue、monetizedPlaybacks、playbackBasedCpm、impressions 和 impressionBasedCpm。

2015 年 10 月 29 日

此更新包含以下更改：

• 更正了 YouTube Reporting API 的 date 维度的文档，以反映日期引用了从太平洋时间 (UTC-8) 零点开始的 24 小时时间段。根据相关规定，文档中的内容从凌晨 0:00（格林威治标准时间）开始。

  此外，YouTube Analytics API 文档也已更新，以指明所有与日期相关的维度（day、7DayTotals、30DayTotals 和 month）都引用从太平洋时间凌晨 12:00 (UTC-8) 开始的日期。

• YouTube Reporting API 的 jobs.reports.list() 方法现在支持 createdAfter 查询参数。如果指定了此参数，该参数表示 API 响应应仅列出在指定日期和时间之后创建的报表，包括包含回填数据的新报表。请注意，此参数值与报告的创建时间有关，而不是与返回的数据相关的日期。

  参数值是一个采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式的时间戳，精确到微秒。示例："2015-10-02T15:01:23.045678Z"。

  我们已更新 YouTube Reporting API 最佳做法，以说明如何使用 createdAfter 参数来避免重复处理同一份报告。

• job 资源的 createTime 属性以及 report 资源的 startTime、endTime 和 createTime 属性的定义都已更正，请注意，属性值精确到微秒，而不是纳秒。此外，所有定义现在都准确反映了属性值是一个时间戳。

2015 年 10 月 8 日

此更新包含以下更改：

• YouTube Analytics API 的 sharingService 维度文档已更新，添加了可能的维度值列表。该列表包含许多新支持的服务。

  YouTube Reporting API 的sharing_service维度定义也已更新，现在列出了新支持的值。大于 59 的枚举值是列表中的新值。

2015 年 9 月 24 日

此更新包含以下更改：

• 新的 YouTube Reporting API 可用于检索批量数据报告，其中包含某个频道或内容所有者的 YouTube 数据分析数据。它专为能够导入大型数据集以及为数据提供过滤、排序和挖掘工具的应用而设计。

  每份 YouTube Reporting API 报告都包含一组预定义的维度和指标。（YouTube Analytics API 报告也使用指标和维度。）在报表中，每行数据都有一个唯一的维度值组合。您可以根据维度值汇总各行的数据，以便计算具体视频、国家/地区、直播视频、已订阅的用户等的指标。

  您可以使用 API 安排报告作业，每个作业标识 YouTube 应生成的报告。设置作业后，YouTube 会生成可异步下载的每日报告。每个报告均包含 24 小时的独特数据。

• 虽然 YouTube API 和 YouTube 报告 API 是不同的 API，但它们都让开发者可以检索 YouTube 数据分析数据。由于这两个 API 都可以访问类似的数据集，因此这两个 API 的文档将作为一个文档集发布。

  • 文档集内的指南标签页包含这两个 API 共用的信息，包括授权 API 请求的说明。
  • 批量报告标签页包含专门针对 YouTube Reporting API 的参考文档和其他内容。
  • 目标查询标签页包含专门针对 YouTube Analytics API 的参考文档和其他内容。
  • 示例标签页列出了可用于这两个 API 中的其中一个的代码示例。
  • 工具标签页列出了有助于开发者实现这两个 API 中的其他资源。

2015 年 8 月 20 日

此更新包含以下更改：

• 为使 API 更易于理解，我们重新编写了 API 文档的结构。因此，这些更改不会描述新功能：

  • 本文档现在包含一个页面，其中列出所有可用的频道报告，另一个页面列出所有可用的内容所有者报告。以前，相关文档包含单独的页面视频报告、频道播放列表报告等。

  • 新的数据模型概览旨在更清晰地介绍此 API 的工作原理。具体而言，本文档会尝试更好地说明 YouTube 如何使用指标、维度和过滤条件来计算报告值。

  • 用于检索报告的 API 的 reports.query 方法现在单独记录。该网页上的信息之前曾出现在一些其他网页上。新页面旨在帮助您更轻松地识别需要发送的信息来检索报告。

2015 年 7 月 22 日

本次更新包含多项更改，所有更改都仅适用于内容所有者：

• 新的adEarnings指标包括所有 Google 出售的广告来源的总估算收入（净收入）。它不是核心指标。对于所有支持 earnings 指标的报告，该 API 均支持 adEarnings 指标。

  此外，earnings 指标的定义也已得到纠正，以反映它的值包括所有 Google 出售的广告来源和非广告来源的总估算收入。以前，该定义错误地指出该指标仅包含来自广告来源的收入。

• 已弃用 primaryAdGrossRevenue 指标，而是改为使用 grossRevenue 指标来检索收入数据。

• 除了已弃用的 primaryAdGrossRevenue 指标外，广告效果报告也不再支持 monetizedPlaybacks 和 playbackBasedCpm 指标。不过，有几个视频报告仍然支持这些指标。

2015 年 6 月 1 日

此更新包含以下更改：

• 该 API 现在支持视频报告的两个新指标：videosAddedToPlaylists 和 videosRemovedFromPlaylists。我们更新了频道和内容所有者的视频报告列表，以标识支持新指标的报告。

  • videosAddedToPlaylists - 符合查询条件的视频被添加到任意 YouTube 播放列表的次数。这些视频可能已添加到视频所有者的播放列表或其他频道的播放列表中。
  • videosRemovedFromPlaylists – 在查询范围内，从任何 YouTube 播放列表中移除视频的次数。这些视频可能已从视频所有者的播放列表或其他频道的播放列表中移除。

  这两个指标都包含默认播放列表，例如“稍后观看”播放列表。但是，系统不会统计自动添加到视频的播放列表，例如频道的上传内容播放列表或用户的观看记录。另请注意，这些指标反映的是新增和删除的绝对数量。因此，如果用户在将视频添加到播放列表后又将其移除，那么指标就会表明该视频已添加到两个播放列表中，并从中移除。

  这些指标的数据从 2014 年 10 月 1 日开始提供。

2015 年 3 月 31 日

此更新包含以下更改：

• 自本公告发布以来，favoritesAdded 和 favoritesRemoved 指标都已弃用。这两项都是核心指标，受服务条款中规定的弃用政策的约束。

2015 年 3 月 16 日

此更新包含以下更改：

• 借助新的 currency 参数，您能够以非美元 (USD) 币种检索收入指标。如果设置了此参数，API 会将 earnings、grossRevenue、playbackBasedCpm 和 impressionBasedCpm 指标的值转换为指定货币。返回的值是根据每天变化的汇率计算得出的估算值。

  此参数值是三个字母的 ISO 4217 货币代码。默认值为 USD。参数定义包含支持的货币代码列表。

2015 年 2 月 25 日

此更新包含以下更改：

• 该 API 现在支持创建和管理 YouTube 数据分析群组的功能，以及检索这些群组报告数据的功能。

  • 创建和管理群组

    此更新引入了用于创建和管理群组的 group 和 groupItem 资源。

    • group 资源表示 Google Analytics（分析）群组，这是一个由频道、视频、播放列表或资产组成的自定义集合（最多可收集 200 项）。该 API 支持将此资源使用 list、insert、update 和 delete 方法。
    • groupItem 资源表示 Google Analytics（分析）群组中的项目。该 API 支持将此资源使用 list、insert 和 delete 方法。

    例如，您可以使用 groups.insert 方法创建组，然后使用 groupItems.insert 方法向该组添加项。

  • 检索群组的报告数据

    维度文档已更新为包含 group 维度，该维度可用作许多渠道报告和内容所有者报告的过滤条件。当您使用 group 过滤条件时，API 会返回该组中所有产品的数据。请注意，该 API 目前不支持为素材资源组创建报告。

  如需详细了解 YouTube 数据分析组，请访问 YouTube 帮助中心。

2015 年 2 月 13 日

此更新包含以下更改：

• 该 API 不再支持 show 维度。

2014 年 8 月 28 日

此更新包含以下更改：

• 现在，该 API 支持在将 video、playlist、channel 和 show 维度用作过滤条件时为这些维度指定多个值。如需指定多个值，请将 filters 参数值设为应过滤 API 响应的视频、播放列表、频道或节目 ID 的英文逗号分隔列表。该参数值最多可指定 200 个 ID。

  如果您为同一个过滤条件指定多个值，则还可以将该过滤条件添加到您为请求指定的维度列表中。即使该过滤条件未被列为特定报表支持的维度，也是如此。如果您将过滤条件添加到维度列表，则 API 也会使用过滤条件值对结果进行分组。

  如需详细了解此功能，请参阅 filters 参数定义。

2014 年 7 月 16 日

此更新包含以下更改：

• 现在，检索渠道报告时，您可以将 ids 参数的值设置为 channel==MINE，从而检索通过身份验证的用户的频道的数据。（您仍可将 ids 参数设为 channel==CHANNEL_ID 以检索指定渠道的数据。）

• 该 API 现在支持播放列表报告，其中包含与播放列表环境中的视频观看次数相关的统计信息。播放列表报告适用于频道和内容所有者。

  所有播放列表报告都支持 views 和 estimatedMinutesWatched 指标，还有一些报告还支持 averageViewDuration 指标。

  此外，所有播放列表报告都支持以下新指标。请注意，这些指标中的每一个值都只能反映网络上发生的播放列表观看次数。

  • playlistStarts：观看者启动播放列表播放的次数。
  • viewsPerPlaylistStart：每次启动播放列表时的平均视频观看次数。
  • averageTimeInPlaylist：观看者在观看播放列表后，观看相应播放列表中视频的平均时长（以分钟为单位）。

  任何检索播放列表报告的请求都必须使用 isCurated 过滤条件，该过滤条件必须设置为 1 (isCurated==1)。

• 该 API 现在支持观众黏度报告。此报告用于衡量视频留住观众的能力。该报告的新 elapsedVideoTimeRatio 维度用于衡量视频在对应的指标值下已播放的时长：

  • audienceWatchRatio 指标用于标识在视频给定时间点观看视频的观看者的绝对比率。该比率的计算方法是：将一部分视频的观看次数与视频的总观看次数进行比较。

    请注意，在某一视频观看过程中，某部分视频可以多次观看（或者完全不观看）。例如，如果用户快退并多次观看视频的同一部分，则视频的该部分的绝对比率可能大于 1。

  • relativeRetentionPerformance 指标反映的是，与 YouTube 上所有类似时长的视频相比，视频在播放期间留住观看者的程度。值为 0 表示在留住观看者方面，视频比在其他类似时长的视频上表现差；而如果值为 1，则表示该视频在留住观看者方面的效果要好于任何其他长度相近的视频。中位数值为 0.5，这表示时长相近的视频有一半的视频在留住观看者方面的表现更好，而一半的视频在留住观看者方面的表现则较差。

  您还可以使用 audienceType 过滤条件，让报告仅返回与自然观看次数、TrueView 插播广告或 TrueView 展示广告获得的观看次数相关的数据。（自然观看次数是用户操作（例如搜索视频或点击推荐视频）的直接结果。）

• 该 API 支持多个与注解相关的新指标。您可以使用之前支持 annotationClickThroughRate 和 annotationCloseRate 指标的任何报表检索下列指标。

  • annotationImpressions：注释总展示次数。
  • annotationClickableImpressions：显示且可以点击的注释的数量。
  • annotationClosableImpressions：已显示且可以关闭的注释的数量。
  • annotationClicks：用户点击的注释的总数。
  • annotationCloses：关闭的注解总数。

  所有新指标都是核心指标，受弃用政策的约束。不过请注意，系统提供自 2013 年 7 月 16 日起的新指标数据。（系统从 2012 年 6 月 10 日开始提供 annotationClickThroughRate 和 annotationCloseRate 指标的数据。）

• 不再将 GOOGLE_SEARCH 报告为 insightTrafficSourceType 维度的单独值。现在，系统会将来自 Google 搜索结果的引荐归因于 EXT_URL 流量来源类型。因此，您再也无法检索将 insightTrafficSourceType 过滤条件设置为 GOOGLE_SEARCH 的 insightTrafficSourceDetail 报告。

2014 年 1 月 31 日

此更新包含以下更改：

• 内容所有者报告文档已更新，表明现在可以针对内容所有者声明或上传的内容检索 subscribersGained 和 subscribersLost 指标。

  针对内容所有者的第一项基本统计信息报告中会显示这项更改，该报告现在支持 claimedStatus 和 uploaderType 过滤条件。

2014 年 1 月 16 日

此更新包含以下更改：

• 在新版面中，示例分为以下几类：

  • 基本统计信息
  • 基于时间
  • 地理位置
  • 播放位置
  • 流量来源
  • 设备/操作系统
  • 受众特征
  • 社交媒体
  • 收入/广告（仅限内容所有者报告）

• 示例请求文档现在包含一些新示例，用于在渠道报告或内容所有者报告中检索省级数据。

  • 针对美国各州和华盛顿特区的省级指标：此报告可检索每个省份的观看次数和统计信息。数据涵盖美国各州和华盛顿特区。该示例使用 province 维度，并使用 filters 参数来限制响应，使其仅包含美国的搜索结果。

  • 加利福尼亚州的观看者受众特征（年龄段和性别）：此报告会检索在加利福尼亚观看了频道视频的观看者的年龄和性别方面的统计信息（对于内容所有者报告，此报告则检索到内容所有者已主张版权的内容）。此示例使用 filters 参数来确保响应仅包含特定省的数据。

• province 维度的定义已更新。请注意，如果 province 包含在 dimensions 参数值中，则请求也必须在 filters 参数值中添加 country==US，以将数据限制为来自美国。

2014 年 1 月 6 日

此更新包含以下更改：

• 罗列了受支持的渠道报告和内容所有者报告的文档已经过重新设计。您无需提供表格来列出所有可能的报告，而是将每个文档按类别分组：

  • 基本统计信息
  • 基于时间
  • 地理位置
  • 播放位置
  • 流量来源
  • 设备/操作系统
  • 受众特征
  • 社交媒体
  • 热门视频

  每个文档都会以标签页列表的形式显示这些类别，您可以点击任意标签页，查看相应类别中支持的报告。

• 该 API 现在支持三个新的地理位置维度：province、continent 和 subContinent。

  • 借助 province 维度，您可以检索美国各州和哥伦比亚特区的统计信息。API 支持此维度的两个用途：

    • 该 API 支持两种按州细分统计信息的报告。这两种报告分别适用于频道和内容所有者。

      • “核心统计信息”报告会提供多项统计信息，包括观看次数和估计观看时长。
      • 按时间生成的报告会提供相同的统计信息，但会每天、7 天、30 天或每月汇总数据。

    • 您可以使用 filters 查询参数来限制报告，使其仅包含特定状态的统计信息。有几种报告支持此类过滤，包括地理位置报告、播放位置报告、流量来源报告、设备报告、操作系统报告、受众特征报告和热门视频报告。

  • continent 维度指定用于标识大洲的联合国 (UN) 统计区域代码。此维度只能用作过滤条件。

  • subContinent 维度指定联合国 (UN) 统计区域代码，用于标识大洲的次级区域。此维度只能用作过滤条件。

    由于每个子区域只与一个大洲关联，因此在使用 subContinent 过滤器时也无需使用 continent 过滤器。（实际上，如果请求使用两个维度，该 API 将返回错误。）

• 文档已更正，insightTrafficSourceDetail 维度不包含 insightTrafficSourceType 值 PROMOTED 作为有效的过滤条件值。

2013 年 9 月 30 日

此更新包含以下更改：

• YouTube Analytics API 现在受服务条款中所述的弃用政策的约束。但是，API 的非核心维度和非核心指标不受弃用政策的约束。更新了维度和指标页面，列出了核心维度和核心指标。此外，我们还更新了这些页面上的定义，以明确识别核心维度和指标。

• API 现在支持使用 EXTERNAL_APP 作为 insightPlaybackLocationType 维度的值。在此次更新之后，自 2013 年 9 月 10 日起，系统不再将播放次数归为 MOBILE 次播放，但在该日期之前发生的移动播放次数仍按该值进行分类。

  经过此次更新，移动设备播放现分为 WATCH、EMBEDDED 或 EXTERNAL_APP 播放，具体取决于播放的具体应用类型。

• API 现在支持使用 PLAYLIST 作为 insightTrafficSourceType 维度的值。该值表示视频观看是通过播放列表推荐的。以前，系统会使用维度的 YT_OTHER_PAGE 类别对这些视图进行分类。

2013 年 7 月 16 日

此更新包含以下更改：

• 现在，该 API 支持按多个维度和指标对报告进行排序。示例请求文档包含一个新示例：按多个维度/指标对请求进行排序，演示了此功能。该请求会检索流量来源数据，并将 sort 参数值设为 day,-views。结果按时间顺序排序，但在每天的结果集中，第一行包含生成观看次数最多的流量来源的数据，第二行包含生成次之次的流量来源的数据，以此类推。

• 该 API 现在支持两种新维度：deviceType 和 operatingSystem，可用于检索观看者观看您视频的设备的相关数据。该 API 支持使用其中一个维度或同时使用这两个维度的报告。

  • 通过deviceType报告，您可以检索不同类型的设备（包括桌面设备、移动设备和平板电脑设备）的观看次数和估计观看时长。您还可以使用 operatingSystem 过滤条件将设备类型报告限制为仅包含运行特定操作系统（例如 Android 或 iOS）的设备的统计信息。

  • 通过 operatingSystem 报告，您可以检索不同操作系统（例如 Android、iOS、Linux 等）的观看次数和估算的观看时长。您还可以使用deviceType过滤条件来限制操作系统报告，使其仅包含特定类型的设备（例如移动设备或平板电脑）的统计信息。

  新的设备类型和操作系统报告适用于频道和内容所有者。

• 我们更新了示例请求文档，现在包含三种渠道报告（针对频道）和三种设备报告（面向内容所有者）。

• insightPlaybackLocationType 维度可能会返回值 YT_OTHER，该值用于标识未使用该维度的其他值分类的视图。

2013 年 5 月 23 日

此更新包含以下更改：

• 内容所有者报告文档已更新，以反映您可以对收入最高的视频报告进行降序排列，以找出收入最高的视频。此报告是“用户活动”和“收入”报告部分的第二个表格中列出的第一个报告。

2013 年 5 月 10 日

此更新包含以下更改：

• YouTube 不再提供实验性 API 功能和服务。现在，我们提供了受弃用政策约束的 YouTube API 列表。

2013 年 5 月 6 日

此更新包含以下更改：

• 该 API 现在支持检索观看时长指标（estimatedMinutesWatched、averageViewDuration 和 averageViewPercentage）以及其他指标，包括观看次数指标、互动指标、收入指标和广告效果指标。

  为反映这一变化，我们更新了频道报告和内容所有者报告的列表。（由于观看时长报告可作为其他列出的报告的一部分进行检索，因此列表现在更短了。）

  API 请求示例文档也已更新。

• 使用 insightPlaybackLocationDetail 和 insightTrafficSourceDetail 维度的报告在以下方面得到增强：

  • 它们现在支持可选的 country 过滤器。

  • 内容所有者现在可以使用以下任何新的 filter 组合来检索这些报告。请注意，所有这些组合也支持可选的 country 过滤条件。

    • 播放位置详情

      • channel,insightPlaybackLocationType==EMBEDDED
      • show,insightPlaybackLocationType==EMBEDDED
      • claimedStatus,insightPlaybackLocationType==EMBEDDED
      • uploaderType,insightPlaybackLocationType==EMBEDDED
      • uploaderType,claimedStatus,insightPlaybackLocationType==EMBEDDED

    • 流量来源详细信息

      • channel,insightTrafficSourceType
      • show,insightTrafficSourceType
      • claimedStatus,insightTrafficSourceType
      • uploaderType,insightTrafficSourceType
      • uploaderType,claimedStatus,insightTrafficSourceType

2013 年 5 月 3 日

此更新包含以下更改：

• 新的示例 API 请求文档提供了一些示例，演示了如何使用 YouTube Analytics API 检索许多不同类型的报告。每个示例都包含请求的检索报告的简要说明，然后显示该请求的维度、指标、过滤条件和排序参数。

• insightTrafficSourceType 维度现在支持将 SUBSCRIBER 作为有效值。此值用于标识通过 YouTube 首页上的 Feed 或 YouTube 订阅功能引荐的视频观看次数。如果您根据此流量来源进行过滤，则 insightTrafficSourceDetail 字段会指定首页 Feed 或从中引用观看次数的其他网页。

2013 年 3 月 28 日

此更新包含以下更改：

• 该 API 现在支持两个新指标，即 annotationClickThroughRate 和 annotationCloseRate，它们与观看者与视频期间显示的注释的互动情况相关。渠道报告和内容所有者报告的列表均已更新，用于标识支持新指标的报告。

  • annotationClickThroughRate - 观看者获得的注释与可点击注释的总展示次数的比率。
  • annotationCloseRate - 观看者关闭的注解与注解总展示次数的比率。

2013 年 3 月 21 日

此更新包含以下更改：

• 现在，该 API 支持收入和广告效果指标以及新的广告效果报告。只有参与 YouTube 合作伙伴计划的 YouTube 内容合作伙伴可以访问这些指标和报告。

  • 新支持的报告支持基于播放的广告效果指标和基于展示次数的广告效果指标。如需详细了解广告效果报告，请参阅内容所有者报告文档。

  • 新支持的指标如下所示。我们更新了内容所有者报告的列表，确定了支持这些指标的报告（包括两种新报告）。

    • earnings - 所有 Google 出售的广告来源的估算收入总额。
    • grossRevenue - Google 或 DoubleClick 合作伙伴的估算总收入。
    • primaryAdGrossRevenue - 该报表所涵盖的视频播放来源于 Google 或 DoubleClick 合作伙伴的估算总收入（按主广告类型汇总）。
    • monetizedPlaybacks - 至少展示过一次广告的播放次数。
    • playbackBasedCpm - 每千次播放的估算毛收入。
    • impressions - 已通过验证的广告展示次数。
    • impressionBasedCpm - 每千次广告展示的估算总收入。

    注意：如需了解完整详情，请参阅指标定义。

  • 任何检索收入或广告效果指标的请求都必须发送授权令牌，使用新的 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围授予访问权限。

• API 文档已经过重新整理，因此不同类型的报告分别显示在不同的页面上。因此，现在有不同的页面，分别介绍了不同类型的频道报告和内容所有者报告。

2013 年 2 月 4 日

此更新包含以下更改：

• API 的参考指南现在提供了示例部分，其中包含的代码示例演示了如何使用 Java、JavaScript、Python 和 Ruby 客户端库调用 API。JavaScript 代码示例与示例应用文档中详述的相同。

2012 年 11 月 14 日

此更新包含以下更改：

• API 参考指南现在提供了 APIs Explorer，使您能够调用 API、查看 API 请求并在响应中检索实际数据。

• 该 API 支持多种面向频道和内容所有者的新报告，具体如下所述。每种报告都可以用作频道报告或内容所有者报告。维度和指标页面也已相应更新。

  • 播放位置报告会指定在不同类型的网页或应用中观看视频的次数。

  • 播放位置详情报告可找出为指定视频带来最多观看次数的嵌入式播放器。它与顶级嵌入播放器相关联，因此可提供比播放位置报告更精细的视图。

  • 流量来源报告可标识源自不同类型引荐来源网址的视频观看次数。

  • “流量来源详细信息”报告可指明为指定视频和指定流量来源类型带来最多观看次数的引荐来源网址。例如，此报告可以帮助您了解为某个特定视频带来了最多流量的相关视频。此报告支持多种流量来源。

  • 观看时长报告会显示观看者观看您内容的时间长度。这些报告可以汇总特定时间范围（天、之前七天、之前 30 天等）或国家/地区的数据。如果报告按天或国家/地区汇总数据，则还可以指定每次视频观看的平均时长以及用户观看的每个视频的平均百分比。

2012 年 10 月 2 日

此更新包含以下更改：

• YouTube Analytics API 现在可供所有开发者使用。您无需先通过 APIs console 中的 Services 面板为项目激活该 API 即可。

• 新的使用入门部分概述了构建使用 YouTube Analytics API 的应用的前提条件和基本步骤。

2012 年 9 月 12 日

此更新包含以下更改：

• 新的了解配额用量部分提供了有关优化 API 配额用量的准则。API 服务器会为每个请求计算查询费用，并且该费用会从 API 使用配额中扣除。由于不同类型的报告可能具有截然不同的查询费用，因此您应该计划高效地使用配额，并且您的应用应该只请求其实际需要的指标和数据。

• 时间维度部分已更新，说明了这些维度指明了 Google Analytics（分析）报告应根据时间段来汇总数据。现在，该 API 还支持下列时间维度：

  • 7DayTotals - 系统会对报告中的数据进行汇总，使每行都包含七天的数据。
  • 30DayTotals - 系统会对报告中的数据进行汇总，让每行都包含 30 天的数据。
  • month – 报告中的数据将按日历月汇总。

  同样，可用的报告部分也已更新，以体现 API 对使用这些维度的报告的支持。

• 更新了报告实体维度部分，以指明用来检索内容所有者报告的 API 请求必须使用以下任一维度（video、channel 或 show）或受支持的 claimedStatus 和 uploaderType 维度组合来过滤数据。

• 该 API 现在支持为热门视频报告提供两种新的排序选项。这些报告可用作频道报告或内容所有者报告，其中包含各个国家/地区的各种指标（观看次数、评论数、顶的次数等），并可按视频对这些指标进行细分。您现在可以根据在视频的观看页面上订阅或退订频道的用户数对这些报告进行排序。

• 我们更新了 subscribersGained 和 subscribersLost 指标的定义，以解释频道可以在多个位置获得或失去订阅者，包括视频观看页面、频道页和 YouTube 首页上显示的指南。当这些指标显示在视频专用报告中时，这些指标仅包含来自指定视频观看页面的统计信息。