修订历史记录

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

2025 年 6 月 24 日

正如我们在 2025 年 3 月 26 日宣布的那样，批量报告 API 将进行更新，以适应新的 Shorts 观看次数变化。已进行以下更改：

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

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

之前的报告版本将保留至 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 日宣布的那样，Targeted Queries API 将会更新，以适应新的 Shorts 观看次数统计方式：

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

这些变更将于 2025 年 4 月 30 日生效，适用于 Targeted Queries API。请务必相应地调整查询。

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

2025 年 4 月 22 日

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

2025 年 3 月 26 日

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

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

YouTube 数据分析（定位查询）和报告（批量报告）API 将更新为包含以下变更：

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

“有针对性的查询”将于 4 月 30 日之前更新，“批量报告”将于 6 月 30 日之前更新。在此之前，观看次数将基于旧的统计方法。Shorts 短视频和频道观看次数与工作室中的 Google Analytics 数据不一致。

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

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

2025 年 3 月 3 日

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

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

合作伙伴已无法再使用每日版权主张（1.0 版）报告。自 2025 年 4 月 30 日起，我们将不再支持此功能。相应地更新了该报告的定义。请改用最新的“每日版权主张”报告。

2024 年 11 月 15 日

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

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

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

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

2024 年 5 月 6 日

YouTube Analytics（定位查询）API 支持以下三种新的频道报告：

此外，我们还增强了观众黏度报告，使其支持以下三项新指标：

2024 年 4 月 7 日

YouTube Analytics（定位查询）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 功能与工作室应用中提供的功能保持一致。
    • 频道播放列表报告不再支持将 subscribedStatus 和 youtubeProduct 维度作为过滤条件。这些过滤条件之前在 YouTube 工作室中不可用，因此这项更改可使 API 功能与工作室应用中提供的功能保持一致。

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

    • 汇总视频指标 提供用户活动和展示指标，这些指标是针对内容所有者播放列表中的所有视频（这些视频也归相应内容所有者所有）汇总而成的。仅当 API 请求未使用 isCurated 维度时，才支持汇总视频指标。
    • 播放列表内指标 反映用户在播放列表页面上的活动和互动情况。这些指标 包含的数据还将包括播放列表中非自有视频带来的观看次数，但前提是这些观看次数发生在播放列表环境中。
    • 支持的播放列表指标部分介绍了播放列表报告支持的汇总视频指标和播放列表内指标。

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

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

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

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

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

2024 年 1 月 19 日

YouTube Analytics（有针对性的查询）API 有多项与频道播放列表报告相关的更新。更新包括一个已弃用的维度以及多个新增和更新的指标：

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

    isCurated 维度已针对渠道报告弃用。自 2024 年 6 月 30 日起，此功能将不再受支持。相应地更新了该维度的定义。

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

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

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

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

    • 汇总视频指标 提供用户活动和展示指标，这些指标是针对频道播放列表中的所有视频（这些视频也归相应频道所有）汇总而成的。仅当 API 请求未使用 isCurated 维度时，才支持汇总视频指标。
    • 播放列表内指标 反映用户在播放列表页面上的活动和互动情况。这些指标 包含的数据还将包括播放列表中非自有视频带来的观看次数，但前提是这些观看次数发生在播放列表环境中。
    • 支持的播放列表指标部分介绍了播放列表报告支持的汇总视频指标和播放列表内指标。

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

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

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

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

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

2023 年 12 月 4 日

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

2022 年 12 月 15 日

YouTube Analytics（定位查询）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 Reporting（批量报告）API 均支持新的流量来源详细信息值：

2022 年 2 月 11 日

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

具体更改如下：

  • 在 YouTube Analytics（定位查询）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（定位查询）API 和 YouTube Reporting（批量报告）API。

2022 年 2 月 2 日

此 YouTube Reporting（批量报告）API 支持新的流量来源维度值，用于指明观看次数源自直播重定向：

对于此流量来源类型，traffic_source_detail 维度指定了观看者是从哪个频道 ID 转过来的。

2020 年 9 月 23 日

YouTube Analytics（定位查询）API 和 YouTube Reporting（批量报告）API 均支持新的流量来源维度值，该值表示观看者是通过在 YouTube Shorts 短视频观看体验中垂直滑动来访问相应内容的：

YouTube Analytics API 中的流量来源详细信息维度 (insightTrafficSourceDetail) 或 YouTube Reporting API 中的流量来源详细信息维度 (traffic_source_detail) 不会针对此新流量来源类型进行填充。

2020 年 7 月 20 日

此更新涵盖了影响 YouTube Analytics（定位查询）API 的两项变更：

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

2020 年 2 月 13 日

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

在这两个 API 中，通知的可能流量来源详细信息值集正在发生变化。 在有针对性的查询中，通知报告为 insightTrafficSourceType=NOTIFICATION。在批量报告中，通知报告为 traffic_source_type=17。

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

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

这些值是针对从 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 天内的观看次数可以通过汇总相应时间段内每天的观看次数来计算。
    • 7 天时间段的 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 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 Analytics（有针对性的查询）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 不支持 JSON-RPC 协议，而 v1 API 支持该协议。再次强调，此弃用并非仅针对 YouTube Analytics API。

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

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

2018 年 2 月 21 日

此更新包含对 YouTube Analytics（有针对性的查询）API 的以下更改：

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

2018 年 1 月 18 日

此更新包含以下更改：

  • YouTube Reporting API（批量报告）

    • 用于标识发生观看的设备的软件系统的 operating_system 维度现在支持以下值：
      • 25：KaiOS

  • YouTube Analytics API（有针对性的查询）

2017 年 12 月 20 日

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

  • API 服务器现在支持对下载报告的请求进行 gzip 压缩。请注意，gzip 压缩不支持其他类型的 API 请求。启用 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 数据分析 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 月 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 相关的维度的说明，指出维度值是指从太平洋时间凌晨 12: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 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 概览的报告特征部分，明确指出报告可通过 API 获取的时间为自生成之日起的 180 天。

    之前，文档中说明报告可涵盖的时间段上限为发送 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 报告已弃用。

    如果您有针对上述任何报告的作业，那么在 2016 年 9 月 22 日之后，YouTube 不会再为这些作业生成新报告。生成的报告仍可在生成之日起 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。

  • 报告 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 会再生成 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 天的历史数据。

    报告 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 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 个或更多 观看次数、estimatedMinutesWatched
    过滤条件：
    使用 0 或 1 country、province、continent、subContinent
    使用 0 或 1 视频、群组
    使用 0 或更多 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

    有关必填字段和选填字段的术语说明，请参阅频道和内容所有者报告的文档。

  • YouTube Analytics API 现在会自动从支持多个值的过滤器（video、playlist 和 channel）中舍弃 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 会允许您将实体添加到群组，但当您尝试检索该群组的报告数据时，API 会返回未经授权的错误。

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

2015 年 11 月 10 日

此更新包含以下更改：

2015 年 10 月 29 日

此更新包含以下更改：

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

    此外，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 中任一 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 货币代码（由三个字母组成）。默认值为 USD。参数定义包含支持的币种代码列表。

2015 年 2 月 25 日

此更新包含以下更改：

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

    • 创建和管理群组

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

      • group 资源表示一个数据分析群组，这是一个由最多 200 个频道、视频、播放列表或资产组成的自定义集合。该 API 支持此资源的 list、insert、update 和 delete 方法。
      • groupItem 资源表示 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”指标。

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

    • playlistStarts：播放列表被观看者播放的次数。
    • viewsPerPlaylistStart：每次启动播放列表时发生的视频观看次数的平均值。
    • averageTimeInPlaylist：观看者在播放列表开始播放后观看该播放列表中的视频的估计平均时长（以分钟为单位）。

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

  • 该 API 现在支持观众黏度报告。此报告用于衡量视频在吸引观众方面的表现。报告的新 elapsedVideoTimeRatio 维度用于衡量相应指标值所对应的视频播放时长：

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

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

    • relativeRetentionPerformance 指标显示了与 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 维度的定义已更新，其中指出，如果 dimensions 参数值中包含 province，则请求还必须通过在 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 字段将指定观看次数的引荐来源，即首页 Feed 或其他网页。

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 - 报告中的数据将进行汇总，以便每行包含七天的数据。
    • 30DayTotals - 报告中的数据将进行汇总，以便每行都包含 30 天的数据。
    • month - 报告中的数据将按日历月进行汇总。

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

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

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

  • 我们更新了subscribersGained和subscribersLost 指标的定义，以说明频道可以在多个位置（包括视频观看页面、频道页面和 YouTube 首页上显示的导视面板）获得或失去订阅者。当这些指标显示在特定于视频的报告中时，它们仅包含指定视频观看页面的统计数据。