修订历史记录

本页面列出了 YouTube Reporting API 和 YouTube Analytics API 的 API 变更和文档更新。这两个 API 都允许开发者访问 YouTube 数据分析中的数据，但方式不同。

2026 年 10 月 30 日

YouTube Reporting API 现在支持以下面向内容所有者的系统管理的报告：

类别 报告名称 报告类型 ID
财务摘要 每月频道调整项摘要 content_owner_channel_adjustments_summary_a1
财务摘要 每月付费功能交易收入 content_owner_transactions_paid_features_revenue_a1
财务摘要 按国家/地区和影片划分的每月 TVOD 交易收入 tvod_content_owner_country_title_tvod_revenue_a1
财务摘要 按国家/地区划分的每月 TVOD 交易收入 tvod_content_owner_country_transactions_tvod_revenue_a1
短视频 唱片公司每月 Shorts 资产创作 music_content_owner_shorts_asset_creations_a1
短视频 唱片公司每月 Shorts 资产观看次数 music_content_owner_shorts_asset_views_a1
短视频 音乐出版商每月短视频资产创作 publisher_content_owner_shorts_asset_creations_a1
短视频 音乐出版商 Shorts 资产每月观看次数 publisher_content_owner_shorts_asset_views_a1
税费 MCN 联属频道每月退税摘要报告 content_owner_affiliate_tax_refund_summary_a1
资产 每周 SRMF 报告 publisher_content_owner_weekly_srmf
资产 音乐人官方频道请求状态每日报告 content_owner_oac_request_status_a1
资产 每日 OAC 请求质量报告 content_owner_oac_quality_status_a1

2026 年 9 月 13 日

YouTube Reporting API 现在支持面向内容所有者的每周参考报告 (content_owner_active_references_a2) 的版本 1.1。

1.1 版引入了以下变更：

  • 添加了 status_detail 字段，该字段提供有关参考文件状态的其他详细信息或原因。
  • 更新 asset_owners 字段，以使用内容所有者显示名称或外部 ID，而不是合作伙伴代码。

该报告的先前版本版本 1.0 (content_owner_active_references_a1) 仍可继续使用。

2026 年 9 月 9 日

YouTube Analytics API 和 YouTube Reporting API 文档已更新，其中添加了以下内容并进行了澄清：

  • 数据新鲜度和延迟时间服务等级协议 (SLA)：在数据模型中添加了专门的部分，说明了 48 到 72 小时的数据处理延迟、结束日期截断到最后一个完全处理的日期，并建议使用 YouTube Data API videos.list 方法获取实时视频统计信息。

  • 频道报告中的货币指标：更新了频道报告授权文档，以阐明如果频道是 YouTube 合作伙伴计划 (YPP) 成员，则使用 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围授权的频道报告支持估算收入和广告效果指标，而未启用的频道会返回 HTTP 403 Forbidden。

  • 查询限制和参数兼容性：在了解报告表格中添加了一条建议说明，阐明无效或互斥的维度、指标和过滤条件组合会返回 HTTP 400 badRequest ("The query is not supported.")。

  • 批量报告中的空维度值：更新了 YouTube Reporting API 报告特征，说明了 video_id 或 channel_id 等维度列包含空字符串，以便保留已删除资源的汇总指标计数，并表示频道级事件。

2026 年 8 月 27 日

YouTube 将统一所有视频格式（长视频、直播和 Shorts 短视频）的公开观看次数统计方法。只要视频开始播放，YouTube 就会统计公开观看次数。

创收资格条件和大多数核心效果指标不受影响，因为它们仍然基于互动指标。创作者的收入仍将根据“感兴趣的 Shorts 观看次数”和“感兴趣的观看时长”计算，您可以在 YouTube 数据分析 > 高级模式中查看这些数据。

YouTube 合作伙伴计划的资格要求没有变化。YouTube 合作伙伴计划的加入要求现在也将称为“有效 Shorts 观看次数”和“有效观看时长”（之前称为“有效公开 Shorts 观看次数”和“有效公开视频观看时长”）。

如需了解详情，请参阅了解 YouTube 内容的表现。

指标 状态 触发器 用途
查看 已更新 视频从第一帧开始播放（包括自动播放、将指针悬停在视频上以及点击/点按播放）。 标准公开观看次数。
感兴趣的观看 未更改 播放继续，超过第一帧，或者用户点击/点按播放。 通过 YouTube 合作伙伴计划创收、大部分核心分析功能（点击率、平均观看时长）以及互动报告。
缩略图展示 未更改 缩略图在没有互动或自动播放的情况下显示。 衡量 Feed 级曝光度和打包情况。

API 文档更新：更新了 YouTube Analytics API 指标和 YouTube Reporting API 指标文档中 engagedViews 指标的定义。

2026 年 6 月 25 日

YouTube Analytics API（定向查询）文档已更新，移除了面向内容所有者的按城市划分的用户活动报告。内容所有者不支持此报告；内容所有者按城市查询用户活动时，将返回空结果。

2026 年 3 月 9 日

ageGroup (YouTube Analytics API) 和 age_group (YouTube Reporting API) 维度现在包含 YouTube 估计未满 18 周岁的用户。

2026 年 1 月 15 日

YouTube Reporting API 现已支持面向频道和内容所有者的覆盖面报告。覆盖面报告提供视频缩略图展示次数和点击率的统计信息。

  • channel_reach_basic_a1和channel_reach_combined_a1报告适用于频道。
  • content_owner_reach_basic_a1 和 content_owner_reach_combined_a1 报告适用于内容所有者。

这些报告支持以下新指标：

  • video_thumbnail_impressions
  • video_thumbnail_impressions_ctr

2025 年 9 月 22 日

之前宣布的报告弃用日期已从 2025 年 9 月 30 日推迟到 2025 年 10 月 31 日。在此之前，针对 Shorts 观看次数变化而更新的旧版报告将继续提供，但版权主张报告 v1.0 (content_owner_active_claims_a1) 和版权主张报告 v1.1 (content_owner_active_claims_a2) 除外，它们仍将于 9 月 30 日弃用。

2025 年 6 月 24 日

正如我们在 2025 年 3 月 26 日宣布的那样，我们将更新批量报告 API，以配合新的 Shorts 观看次数统计方式。我们做出了以下更改：

  • 我们已为包含观看次数的每个报告（即大多数报告）创建了新的报告版本。每个受影响报告的版本号都增加了一个，例如从版本 a2 变为版本 a3。
  • 对于 Shorts 短视频，观看次数将统计短视频开始播放和重放的次数。对于视频，没有任何变化。
  • 更新后的报告将包含一个新列 engaged_views，该列将反映之前的观看次数统计方法。

这些变更将于 2025 年 6 月 30 日起对 Bulk Reports API 生效。请务必相应地调整您的报告处理方式。

旧版报告将保留至 2025 年 9 月 30 日。2025 年 9 月 30 日之后，旧版本将被弃用。请务必迁移到最新版本。

最后，请务必在处理报告时遵循最佳实践，以免报告日后发生变化时破坏您的处理流水线。

下表显示了每种报告类型的新报告版本：

YouTube 数据分析的批量数据报告

频道报告 - 视频报告
报告名称 过往版本 最新版本
用户活动 channel_basic_a2 channel_basic_a3
用户活动（按省份） channel_province_a2 channel_province_a3
播放位置 channel_playback_location_a2 channel_playback_location_a3
流量来源 channel_traffic_source_a2 channel_traffic_source_a3
设备类型和操作系统 channel_device_os_a2 channel_device_os_a3
字幕 channel_subtitles_a2 channel_subtitles_a3
合并 channel_combined_a2 channel_combined_a3
频道报告 - 播放列表报告
报告名称 过往版本 最新版本
用户活动 playlist_basic_a1 playlist_basic_a2
用户活动（按省份） playlist_province_a1 playlist_province_a2
播放位置 playlist_playback_location_a1 playlist_playback_location_a2
流量来源 playlist_traffic_source_a1 playlist_traffic_source_a2
设备类型和操作系统 playlist_device_os_a1 playlist_device_os_a2
合并 playlist_combined_a1 playlist_combined_a2
内容所有者报告 - 视频报告
报告名称 过往版本 最新版本
用户活动 content_owner_basic_a3 content_owner_basic_a4
用户活动（按省份） content_owner_province_a2 content_owner_province_a3
播放位置 content_owner_playback_location_a2 content_owner_playback_location_a3
流量来源 content_owner_traffic_source_a2 content_owner_traffic_source_a3
设备类型和操作系统 content_owner_device_os_a2 content_owner_device_os_a3
字幕 content_owner_subtitles_a2 content_owner_subtitles_a3
合并 content_owner_combined_a2 content_owner_combined_a3
内容所有者报告 - 播放列表报告
报告名称 过往版本 最新版本
用户活动 content_owner_playlist_basic_a1 content_owner_playlist_basic_a2
用户活动（按省份） content_owner_playlist_province_a1 content_owner_playlist_province_a2
播放位置 content_owner_playlist_playback_location_a1 content_owner_playlist_playback_location_a2
流量来源 content_owner_playlist_traffic_source_a1 content_owner_playlist_traffic_source_a2
设备类型和操作系统 content_owner_playlist_device_os_a1 content_owner_playlist_device_os_a2
合并 content_owner_playlist_combined_a1 content_owner_playlist_combined_a2
内容所有者报告 - 素材资源报告
报告名称 过往版本 最新版本
用户活动 content_owner_asset_basic_a2 content_owner_asset_basic_a3
用户活动（按省份） content_owner_asset_province_a2 content_owner_asset_province_a3
视频播放位置 content_owner_asset_playback_location_a2 content_owner_asset_playback_location_a3
流量来源 content_owner_asset_traffic_source_a2 content_owner_asset_traffic_source_a3
设备类型和操作系统 content_owner_asset_device_os_a2 content_owner_asset_device_os_a3
合并 content_owner_asset_combined_a2 content_owner_asset_combined_a3

系统管理的报告 - 财务（非音乐）

内容所有者报告 - Shorts 报告（非音乐）
报告名称 过往版本 最新版本
全球广告收入摘要 content_owner_shorts_global_ad_revenue_summary_a1 content_owner_shorts_global_ad_revenue_summary_a2
每日广告收入摘要 content_owner_shorts_day_ad_revenue_summary_a1 content_owner_shorts_day_ad_revenue_summary_a2
国家/地区广告收入摘要 content_owner_shorts_country_ad_revenue_summary_a1 content_owner_shorts_country_ad_revenue_summary_a2
广告收入摘要 content_owner_shorts_ad_revenue_summary_a1 content_owner_shorts_ad_revenue_summary_a2

系统管理的报告 - 非财务

内容所有者报告 - 版权主张报告
报告名称 过往版本 最新版本
当前的声明 content_owner_active_claims_a2 content_owner_active_claims_a3
内容所有者报告 - 视频元数据报告
报告名称 过往版本 最新版本
视频元数据 content_owner_video_metadata_a3 content_owner_video_metadata_a4
内容所有者报告 - 素材资源报告
报告名称 过往版本 最新版本
素材资源 content_owner_asset_a2 content_owner_asset_a3
资产冲突 content_owner_asset_conflict_a2 content_owner_asset_conflict_a3

2025 年 4 月 24 日

正如我们在 2025 年 3 月 26 日宣布的那样，我们将更新定向查询 API，以配合新的 Shorts 观看次数统计方式：

  • 对于 Shorts 短视频，views现在将统计短视频开始播放和重放的次数。
  • 新指标 engagedViews 将反映之前的观看次数统计方法。engagedViews将与views一起在所有报告中提供。

对于定向查询 API，这些变更将于 2025 年 4 月 30 日生效。请务必相应地调整查询。

请查看此修订历史记录，了解 Bulk Reports API 将在何时发生哪些变更。

2025 年 4 月 22 日

正如 2024 年 4 月 7 日所宣布的那样，isCurated 维度已在频道报告和内容所有者播放列表报告中弃用。自 2024 年 12 月 31 日起，该维度将不再受支持。该维度已从报告和文档中移除。

2025 年 3 月 26 日

此更新包含以下与 YouTube 数据分析和 YouTube Reporting API 相关的变更：

自 2025 年 3 月 31 日起，YouTube 将更改 Shorts 观看次数的统计方式。过去，短视频的播放时长达到一定的秒数之后，系统才会统计一次 Shorts 观看。现在，“观看次数”这项指标将统计短视频开始播放或重放的次数，而且没有最低观看时长要求。 了解详情

YouTube 数据分析 API（定向查询）和 YouTube Reporting API（批量报告）将进行以下更新：

  • 对于 Shorts 短视频，views统计的是短视频开始播放或重放的次数。
  • 我们将推出一个新指标 engagedViews，该指标将采用之前的观看次数统计方法。
  • 如果您拥有频道或有权访问频道数据，则可以查询更新后的观看次数和互动观看次数。

定向查询将于 4 月 30 日之前更新，批量报告将于 6 月 30 日之前更新。在此之前，观看次数将根据旧方法计算。Shorts 观看次数和频道观看次数与 YouTube 工作室中的数据分析不一致。

此外，之前宣布弃用的每日版权主张（1.0 版）报告已推迟。

查看此修订历史记录，了解 API 的变更时间。

2025 年 3 月 3 日

此更新包含以下与 YouTube Reporting API 相关的变更：

注意：这是一则弃用公告。

每日版权主张（1.0 版）报告已弃用，合作伙伴无法再使用。自 2025 年 4 月 30 日起，该版本将不再受支持。该报告的定义已相应更新。请改用最新的每日版权主张报告。

2024 年 11 月 15 日

注意：以下变更将于 2024 年 11 月 18 日生效。

YouTube Analytics (Targeted Queries) API 文档已更新，其中指出，对于流量来源报告，如果查询的视频数量乘以日期范围内的天数所得结果超过 50,000，则 API 的 reports.query 方法现在会返回错误。例如，如果查询要检索 500 个视频 ID 的数据，则最多可以请求 100 天的数据。

此变更会影响频道和内容所有者的报告。

如需减少请求返回的行数，请将查询拆分为多个查询，每个查询指定较少的视频或设置较短的日期范围。通常，对于大型数据集，建议使用批量报告。

2024 年 5 月 6 日

YouTube 数据分析 (定向查询) API 支持三种新的频道报告：

此外，观众黏度报告也得到了增强，支持以下三个新指标：

2024 年 4 月 7 日

YouTube 数据分析（定向查询）API 进行了多项与内容所有者播放列表报告相关的更新。这些更新与 2024 年 1 月 19 日公布的频道播放列表报告相关更新相同。

以下修订历史记录条目提供的信息与 2024 年 1 月 19 日的条目几乎相同。不过请注意，内容所有者播放列表报告对 isCurated 维度的支持将持续到 2024 年 12 月 31 日，而频道播放列表报告对该维度的支持将持续到 2024 年 6 月 30 日。

  • 注意：这是一则弃用公告。

    isCurated 维度已在内容所有者播放列表报告中弃用。自 2024 年 12 月 31 日起，该功能将不再受支持。该维度的定义已相应更新。

    为了在移除 isCurated 维度时保持向后兼容性，您还必须更新代码，以便仅针对播放列表报告检索 playlistViews 指标，而不是 views 指标。由于播放列表报告仍支持 views 指标（尽管含义不同），因此如果您不更新指标名称，API 仍会返回数据。当然，您也可以修改应用，以检索和显示 views 和 playlistViews。

    除了 isCurated 维度之外，新报告中也不再支持以下 API 功能：

    • 新的频道播放列表报告不支持地理位置过滤条件，例如 continent 和 subcontinent。
    • 新的频道播放列表报告不再支持 redViews 和 estimatedRedMinutesWatched 指标。这些指标在 YouTube 工作室中不可用，因此这项变更使 API 功能与 YouTube 工作室应用中提供的功能保持一致。
    • 频道播放列表报告不再支持将subscribedStatus和youtubeProduct维度用作过滤条件。这些过滤条件在 YouTube 工作室中不可用，因此这项变更使 API 功能与工作室应用中提供的功能保持一致。

  • 内容所有者报告文档的播放列表报告部分已更新，更全面地说明了播放列表报告支持的指标类型：

    • 汇总视频指标提供内容所有者播放列表中所有视频（也归该内容所有者所有）的用户活动和展示指标汇总。只有不使用 isCurated 维度的 API 请求才支持汇总视频指标。
    • 播放列表内指标反映了用户在播放列表页面上的用户活动和互动度。这些指标包含的数据还包括播放列表中非自有视频的观看次数，但仅限于在播放列表上下文中发生的观看。
    • 支持的播放列表指标部分指明了播放列表报告支持的汇总视频指标和播放列表内指标。

  • 内容所有者的播放列表报告支持以下新的播放列表内指标。请注意，只有在检索报告的 API 请求不使用 isCurated 维度时，才支持这些指标。如需了解每个指标的定义，请参阅指标文档：

  • views 指标的行为现在取决于检索播放列表报告的 API 请求是否使用了 isCurated 维度：

    • 当请求包含 isCurated 维度时，views 指标是播放列表内指标，表示在内容所有者的播放列表中观看视频的次数。
    • 如果请求不包含 isCurated 维度，则 views 指标是一个汇总视频指标，用于指定内容所有者的播放列表中的视频被观看的总次数，无论这些观看是否发生在播放列表上下文中。汇总总数仅包括与拥有播放列表的频道相关联的内容所有者所拥有的视频的观看次数。

      在这些不使用 isCurated 维度的报告中，playlistViews 指标表示视频在播放列表上下文中被观看的次数。该指标会统计播放列表中所有视频的观看次数，无论这些视频归哪个频道所有。

  • 对于每个播放列表报告，内容所有者报告文档现在包含一些表格，其中显示了该报告支持的指标，具体取决于 API 请求是否包含 isCurated 维度。如需查看示例，请参阅定义基于时间的播放列表报告的部分。

2024 年 1 月 19 日

YouTube 数据分析 (定向查询) API 进行了多项与频道播放列表报告相关的更新。更新内容包括一个已弃用的维度以及多个新增和更新的指标：

  • 注意：这是一则弃用公告。

    isCurated 维度已在频道报告中弃用。自 2024 年 6 月 30 日起，我们将不再支持该功能。该维度的定义已相应更新。

    为了在移除 isCurated 维度时保持向后兼容性，您还必须更新代码，以便仅针对播放列表报告检索 playlistViews 指标，而不是 views 指标。由于播放列表报告仍支持 views 指标（尽管含义不同），因此如果您不更新指标名称，API 仍会返回数据。当然，您也可以修改应用，以检索和显示 views 和 playlistViews。

    除了 isCurated 维度之外，新报告中也不再支持以下 API 功能：

    • 新的频道播放列表报告不支持地理位置过滤条件，例如 continent 和 subcontinent。
    • 新的频道播放列表报告不再支持 redViews 和 estimatedRedMinutesWatched 指标。这些指标在 YouTube 工作室中不可用，因此这项变更使 API 功能与 YouTube 工作室应用中提供的功能保持一致。
    • 频道播放列表报告不再支持将subscribedStatus和youtubeProduct维度用作过滤条件。这些过滤条件在 YouTube 工作室中不可用，因此这项变更使 API 功能与工作室应用中提供的功能保持一致。

  • 频道报告文档的播放列表报告部分已更新，更全面地说明了播放列表报告支持的指标类型：

    • 汇总视频指标提供频道播放列表中所有视频（也归该频道所有）的汇总用户活动和展示指标。只有不使用 isCurated 维度的 API 请求才支持汇总视频指标。
    • 播放列表内指标反映了用户在播放列表页面上的用户活动和互动度。这些指标包含的数据还包括播放列表中非自有视频的观看次数，但仅限于在播放列表上下文中发生的观看。
    • 支持的播放列表指标部分指明了播放列表报告支持的汇总视频指标和播放列表内指标。

  • 频道的播放列表报告支持以下新的播放列表中指标。 内容所有者报告尚不支持这些指标。请注意，只有在检索报告的 API 请求不使用 isCurated 维度时，这些指标才受支持。如需了解每个指标的定义，请参阅指标文档：

  • views 指标的行为现在取决于检索播放列表报告的 API 请求是否使用了 isCurated 维度：

    • 当请求包含 isCurated 维度时，views 指标是一个播放列表内指标，表示在频道播放列表的上下文中观看视频的次数。
    • 如果请求不包含 isCurated 维度，则 views 指标是一个汇总视频指标，用于指定频道播放列表中的视频被观看的总次数，无论这些观看是否发生在播放列表上下文中。汇总总数仅包括播放列表所属频道拥有的视频的观看次数。

      在这些不使用 isCurated 维度的报告中，playlistViews 指标表示视频在播放列表上下文中被观看的次数。该指标会统计播放列表中所有视频的观看次数，无论这些视频归哪个频道所有。

  • 对于每个播放列表报告，频道报告文档现在包含一些表格，其中显示了该报告支持的指标，具体取决于 API 请求是否包含 isCurated 维度。如需查看示例，请参阅定义基于时间的播放列表报告的部分。

2023 年 12 月 4 日

YouTube 数据分析 (定向查询) API 已更新，合并了两个 insightTrafficSourceType 维度值。以前，该维度会区分作为播放列表的一部分播放的视频 (PLAYLIST) 和源自列出播放列表中所有视频的网页的观看次数 (YT_PLAYLIST_PAGE)。今后，这两种类型的观看次数都将与 PLAYLIST 维度值相关联。

2022 年 12 月 15 日

YouTube 数据分析 (定向查询) API 支持两个新维度和一个新报告：

  • 新增了一份按城市显示用户活动的报告。此报告适用于频道和内容所有者。 此报告包含新的 city 维度，该维度标识了 YouTube 估算的用户活动发生地所在的城市。

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

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

  • YouTube Analytics API 示例请求指南现在包含这两个新维度的示例。

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

2022 年 8 月 26 日

YouTube 数据分析 (定向查询) API 和 YouTube Reporting (批量报告) API 均支持新的流量来源详细信息值：

2022 年 2 月 11 日

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

具体变更如下：

  • 在 YouTube 数据分析 (定向查询) API 中，gender 维度目前支持两个值：female 和 male。自 2022 年 8 月 11 日起，该维度将支持三个值：female、male 和 user_specified。
  • 在 YouTube Reporting (批量报告) API 中，gender 维度目前支持三个值：FEMALE、MALE 和 GENDER_OTHER。在 2022 年 8 月 11 日当天或之后，支持的值集将更改为 FEMALE、MALE 和 USER_SPECIFIED。

2022 年 2 月 9 日

自 2021 年 12 月 13 日起，我们更新了两个指标，以排除循环播放的剪辑流量。此项变更会同时影响 YouTube Analytics (Targeted Queries) API 和 YouTube Reporting (Bulk Reports) API。

2022 年 2 月 2 日

此 YouTube Reporting (批量报告) API 支持一个新的流量来源维度值，该值表示观看次数来自直播跳转：

对于此流量来源类型，traffic_source_detail 维度指定了观看者被引荐时所在的频道 ID。

2020 年 9 月 23 日

YouTube Analytics (Targeted Queries) API 和 YouTube Reporting (Bulk Reports) API 均支持新的流量来源维度值，该值表示观看者是通过在 YouTube Shorts 观看体验中垂直滑动而进入的：

对于这种新的流量来源类型，流量来源详细信息维度（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 个增加到 500 个。

2020 年 2 月 13 日

此更新包含与 YouTube 数据分析（定向查询）API 和 YouTube Reporting（批量报告）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 数据分析 (定向查询) API 相关的变更：

  • 注意：这是一则弃用公告。

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

    请注意，用户可以使用 day 维度进行查询，并汇总或推导 7 天或 30 天时间段内的数据，从而重现这些维度的一些数据。例如：

    • 7 天内的观看次数可以通过汇总该时间段内每天的观看次数来计算。
    • 7 天时间段内的 viewerPercentage 的计算方法是：将每天发生的观看次数乘以当天的 viewerPercentage，得出当天观看视频时已登录的观看者人数。然后，可以将整个时间段内已登录观看者的数量相加，再除以该时间段内的总观看次数，即可得出整个时间段内的 viewerPercentage。
    • 无法计算 7 天内的唯一身份观看者人数，因为同一观看者可能会在不同日期被计算为唯一身份观看者。不过，您或许可以使用 month 维度（而非 30DayTotals 维度）来推断 30 天内的唯一身份观看者人数数据。请注意，month 维度是指日历月，而 30DayTotals 维度则根据指定的开始日期和结束日期计算 30 天的时间段。

2019 年 6 月 27 日

此更新包含以下与 YouTube 数据分析 (定向查询) API 相关的变更：

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

2018 年 11 月 1 日

此更新包含以下与 YouTube 数据分析 (定向查询) API 相关的变更：

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

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

2017 年 9 月 17 日

此更新包含以下与 YouTube 数据分析 (定向查询) API 相关的变更：

  • 数据模型概览文档中新增了数据匿名化部分，其中说明了如果相关指标达不到特定阈值，YouTube 数据分析中会有一些数据因受到限制而不予显示。这可能发生在多种情况下。在实践中，这意味着如果出现以下情况，报告可能不会包含您的所有（或任何）数据：

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

      或

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

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

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

2018 年 6 月 18 日

此更新对 YouTube 数据分析 (定向查询) 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 数据分析 (定向查询) API 进行了以下更改：

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

2018 年 5 月 22 日

此更新包含以下与 YouTube Reporting（批量报告）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 日

YouTube 数据分析 (定向查询) API (v2) 的第 2 版现已公开发布。以下列表列出了与新 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）在 v2 API 中使用驼峰命名法 (endDate)，而不是连字符。此项更改使整个 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 不支持 API v1 支持的 JSON-RPC 协议。同样，此次弃用并非仅针对 YouTube Analytics API。

  • 注意：这是一则弃用公告。

    该 API 的版本 1 (v1) 现已弃用，将在 2018 年 10 月 31 日之后不再受支持。届时，向 v1 API 发出的所有请求都将停止运行。因此，请务必在 2018 年 10 月 31 日之前升级到 v2 API，以免影响您通过 API 访问 YouTube 数据分析数据。

2018 年 2 月 21 日

此更新对 YouTube 数据分析 (定向查询) API 进行了以下更改：

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

2018 年 1 月 18 日

此更新包含以下更改：

  • YouTube Reporting API（批量报告）

    • operating_system 维度用于标识视频播放设备的软件系统，现在支持以下值：
      • 25：KaiOS

  • YouTube Analytics API（定向查询）

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 Analytics 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 Gaming
      • 87：YouTube Kids
      • 88：YouTube TV

      此外，文档中用于标识值 52 的名称已更新为 Kakao (Kakao Talk)，以便更清楚地将其与值 73 (Kakao Story) 区分开来。此变更并不反映 API 行为或与这些服务共享的视频分类有任何变化。

  • YouTube Analytics API（定向查询）

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

2017 年 3 月 28 日

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

2017 年 3 月 17 日

此更新包含以下更改：

2017 年 3 月 3 日

此更新包含以下更改：

  • YouTube Reporting API（批量报告）

    • date 维度的定义已更正，现在该维度值是指在指定日期（年、月、日）的太平洋时间凌晨 12:00 开始，到太平洋时间晚上 11:59 结束的时间段。太平洋时间为 UTC-7 或 UTC-8，具体取决于一年中的时间。

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

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

    • operating_system 维度用于标识视频播放设备的软件系统，现在支持以下值：
      • 22：Tizen
      • 23：Firefox
      • 24：RealMedia

    • content_owner_basic_a1 报告类型的所有报告作业均已删除。该报告类型已于 2016 年 8 月 19 日完全弃用，但之前生成的 content_owner_basic_a1 报告在生成之日起 180 天内仍可查看。因此，部分报告在 2017 年 2 月 19 日之前仍可访问。不过，由于报告不再可用，因此与报告关联的作业也不再需要。

  • YouTube Analytics API（定向查询）

    • 与time periods相关的维度的说明已更正，其中指出维度值是指从指定日期、月份和年份的太平洋时间零点开始，到太平洋时间晚上 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 Analytics API 现在支持可选的 include-historical-channel-data 参数。请注意，此参数仅在检索内容所有者报告时才相关。

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

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

  • 如果参数值为 false，则系统会根据任何给定频道与内容所有者关联的日期，返回该频道的观看时长和观看次数数据。

    请务必注意，不同频道可能是在不同日期与内容所有者关联的。如果 API 请求检索的是多个频道的数据，并且参数值为 false，则 API 响应包含基于每个相应频道的关联日期的观看时长和观看次数数据。
  • 如果参数值为 true，则响应会根据 API 请求中指定的开始日期和结束日期，返回所有频道的观看时长和观看次数数据。

2016 年 12 月 15 日

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

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

2016 年 11 月 11 日

此更新包含以下更改：

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

2016 年 11 月 8 日

此更新对 YouTube Analytics 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 Analytics API 的 uniques 指标已被弃用。这不是核心指标，其支持服务将于 2016 年 10 月 31 日终止。

2016 年 9 月 15 日

此更新包含以下 YouTube Reporting API 变更：

2016 年 8 月 19 日

此更新包含以下 YouTube Reporting API 变更：

2016 年 8 月 11 日

此更新包含以下更改：

  • 新发布的《YouTube API 服务的服务条款》（以下简称“更新后的条款”）在 YouTube 工程和开发者博客中进行了详细讨论，对当前《服务条款》进行了大量更新。除了将于 2017 年 2 月 10 日生效的更新后的条款之外，此次更新还包含多份支持文档，旨在帮助解释开发者必须遵守的政策。

    更新后条款的修订历史记录中介绍了整套新文档。此外，未来对更新后的条款或这些支持文档所做的更改也会在该修订历史记录中进行说明。您可以通过该文档中的链接订阅 RSS Feed，其中列出了该修订历史记录中的更改。

2016 年 8 月 10 日

此更新包括以下变更：

  • YouTube Analytics API（定向查询）

    • 注意：这是一则弃用公告。

      下表中的指标即将弃用。同时，我们还会引入引用相同数据的新指标。实际上，这意味着旧指标将被重命名，但 YouTube 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 日。

      例如，在 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 Analytics 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 文档已更新，以反映对众多频道和内容所有者报告中的卡片指标的支持。新支持的指标包括：

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

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。

      这两份新命名的报告与之前的报告有以下不同：

    请注意，如果您已有作业来创建这些报告的任何旧版本，则需要为重命名的报告创建新作业。随着新版报告的发布，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。不过请注意，此指标仅出现在两个报告中，而这两个报告将在此次更新中被弃用。如上所述，在这些报告的新版本中，此指标已重命名为 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 报告已被弃用。如果您有针对该报告的作业，则在 2016 年 8 月 19 日之后，YouTube 将不会再为该作业生成新报告。生成的报告在生成后 180 天内仍可供查看。

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

    • reportType 资源的 deprecateTime 属性指定了报告类型弃用的日期和时间。只有已宣布弃用的报告才具有此属性的值，该值表示 YouTube 将停止生成该类型报告的日期。

      在宣布弃用某种报告类型后，YouTube 会继续生成该类型的报告三个月。例如，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 请求发送日期之前最长 6 个月的数据。

    • 文档已更新，以反映以下事实：该 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 Inbox
    • 84：Android Messenger
  • 在 YouTube Analytics API 中，sharingService 维度支持以下新值：
    • ANDROID_MESSENGER：Android Messenger
    • INBOX：Google Inbox
    • 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 Analytics 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。

    文档已更新，其中指出了可供频道和内容所有者使用的新播放详细报告。此外，许多其他报告也已更新，注明这些维度中的一个或多个可选择用作这些报告中的维度和/或过滤条件。

  • 我们更改了报告说明表格的格式，以便您更轻松地确定可用于检索每份报告的有效维度、指标和过滤条件组合。下表说明了频道的“设备类型”报告，并展示了新格式：

    属性 值
    尺寸：
    必填 deviceType
    使用 0 或更多 day、liveOrOnDemand、subscribedStatus、youtubeProduct
    指标：
    使用 1 个或多个 views、estimatedMinutesWatched
    过滤条件：
    使用 0 或 1 国家/地区、province、continent、subContinent
    使用 0 或 1 video、group
    使用 0 或更多 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

    频道和内容所有者报告的文档中介绍了必填字段和选填字段的术语。

  • 现在，如果 API 用户无法从支持多个值的过滤条件（video、playlist 和 channel）中检索数据，YouTube Analytics API 会自动丢弃这些实体。以前，如果 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 日

此更新包含以下更改：

2015 年 10 月 29 日

此更新包含以下更改：

  • YouTube Reporting API 的 date 维度文档已更正，以反映日期是指从太平洋时间 (UTC-8) 凌晨 12:00 开始的 24 小时。之前，文档中指出日期从凌晨 12:00 (GMT) 开始。

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

  • 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 Analytics API 和 YouTube Reporting 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 日

此更新包含以下更改：

2015 年 3 月 16 日

此更新包含以下更改：

  • 借助新的 currency 参数，您可以检索以美元 (USD) 以外的货币表示的收入指标。如果设置了该参数，API 会将 earnings、grossRevenue、playbackBasedCpm 和 impressionBasedCpm 指标的值转换为指定货币。返回的值是使用每日变化的汇率计算得出的估算值。

    参数值是符合 ISO 4217 标准、由 3 个字母组成的货币代码。默认值为 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 日

此更新包含以下更改：

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

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

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

2014 年 7 月 16 日

此更新包含以下更改：

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

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

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

    此外，所有播放列表报告都支持以下新指标。请注意，这些指标仅反映在网页上发生的播放列表观看次数。

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

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

    • audienceWatchRatio 指标可确定在视频中给定时间点观看视频的观看者的绝对比例。该比率的计算方法是：将视频中某个片段的观看次数与视频的总观看次数进行比较。

      请注意，在一次视频观看中，视频的某个部分可能会被观看多次（或根本未被观看）。例如，如果用户多次回放并观看视频的同一部分，则该部分视频的绝对比例可能会大于 1。

    • relativeRetentionPerformance指标显示的是，与 YouTube 上所有时长相近的 YouTube 视频相比，您的视频在播放期间吸引观看者继续观看的能力。值为 0 表示该视频在观众黏度方面比任何其他时长相近的视频都要差，而值为 1 则表示该视频在观众黏度方面比任何其他时长相近的视频都要好。中位值为 0.5 表示，在时长相近的视频中，有一半视频的观众黏度高于该视频，另一半视频的观众黏度低于该视频。

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

  • 该 API 支持多个与注释相关的新指标。下面列出的指标可以通过之前支持 annotationClickThroughRate 和 annotationCloseRate 指标的任何报告进行检索。

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

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

2014 年 1 月 31 日

此更新包含以下更改：

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 过滤条件来限制操作系统报告，使其仅包含特定类型设备（例如移动设备或平板电脑）的统计信息。

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

  • 示例请求文档已更新，其中包含 3 个频道设备报告和 3 个内容所有者设备报告。

  • insightPlaybackLocationType 维度可能会返回 YT_OTHER 值，该值用于标识未使用该维度的其他值之一进行分类的观看。

2013 年 5 月 23 日

此更新包含以下更改：

2013 年 5 月 10 日

此更新包含以下更改：

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 首页上的动态或 YouTube 订阅功能带来的视频观看次数。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段将指定首页动态或引荐观看次数的其他页面。

2013 年 3 月 28 日

此更新包含以下更改：

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 支持面向频道和内容所有者的多项新报告，具体如下所述。每个报告都可作为频道报告或内容所有者报告提供。维度和指标页面也已相应更新。

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

    • 播放位置详细报告会列出为指定视频带来最多观看次数的嵌入式播放器。它通过识别与热门嵌入式播放器关联的网址，提供比播放位置报告更精细的视图。

    • 流量来源报告会显示来自不同类型引荐来源的视频观看次数。

    • 流量来源详细报告会找出为指定视频和指定流量来源类型带来最多观看次数的引荐来源。例如，此报告可以显示为特定视频带来最多流量的相关视频。此报告支持多种流量来源。

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

2012 年 10 月 2 日

此更新包含以下更改：

  • YouTube Analytics API现已面向所有开发者推出。您可以在 APIs console 的服务面板中为项目启用该 API，而无需先申请访问权限。

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

2012 年 9 月 12 日

此更新包含以下更改：

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

  • 时间维度部分已更新，说明了这些维度表示 Google Analytics 报告应根据时间段汇总数据。该 API 现在支持以下额外的时间维度：

    • 7DayTotals - 报告中的数据将汇总，以便每行包含 7 天的数据。
    • 30DayTotals - 报告中的数据将汇总，以便每行包含 30 天的数据。
    • month - 报告中的数据将按日历月汇总。

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

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

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

  • subscribersGained和subscribersLost 指标的定义已更新，以说明频道可以在多个位置获得或失去订阅者，包括视频观看页面、频道页面和 YouTube 首页上显示的导视栏。当这些指标出现在特定视频的报告中时，它们仅包含来自指定视频观看页面的统计信息。