本页列出了 YouTube Reporting API 和 YouTube Analytics API 的 API 变更和文档更新。这两种 API 都能够让开发者访问 YouTube 数据分析数据,只是方法不同。订阅此更改日志。
2024 年 5 月 6 日
YouTube Analytics(定位查询)API 支持三种新的频道报告:
-
按 DMA 细分的用户活动报告是一种地理位置报告,按特定媒体市场区域 (DMA) 提供用户活动统计信息。对于此报告,您必须将
filters
参数值设置为country==US
。 -
同时观看人数报告显示单个直播视频不同部分的同时观看人数。
-
“会员取消人数”报告提供的统计信息显示了用户取消频道会员的原因。
此报告使用新的
membershipsCancellationSurveyReason
维度,指定用户取消频道会员的原因。此外,它还采用了新的membershipsCancellationSurveyResponses
指标,该指标可表明有多少频道会员功能因该原因而被取消。
此外,观众黏度报告得到了增强,可支持以下三个新指标:
2024 年 4 月 7 日
YouTube Analytics(定位查询)API 有一些与内容所有者播放列表报告相关的更新。这些更新与 2024 年 1 月 19 日发布的频道播放列表报告相关更新相同。
以下修订历史记录条目提供的信息与 2024 年 1 月 19 日的条目几乎相同。但请注意,在 2024 年 12 月 31 日之前,内容所有者播放列表报告将支持 isCurated
维度,而频道播放列表报告在 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
维度的情况下,这些指标才受支持。如需了解每个指标的定义,请参阅metrics文档: -
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
维度的情况下,这些指标才受支持。如需了解每个指标的定义,请参阅metrics文档: -
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 Analytics API 请求示例指南现在包含这两个新维度的示例。
-
对
7DayTotals
和30DayTotals
维度的引用已从文档中移除。我们已于 2019 年 10 月宣布弃用这些维度。
2022 年 8 月 26 日
YouTube 数据分析(定位查询)API 和 YouTube 报告(批量报告)API 均支持新的流量来源详情值:
- 在 YouTube Analytics API(定位查询)API 中,如果
insightTrafficSourceType
维度的值为SUBSCRIBER
,则可以将insightTrafficSourceDetail
值设置为podcasts
,这表示流量是从播客目标网页引荐的。 - 在 YouTube Reporting (Bulk Reports) API 中,如果
traffic_source_type
维度的值为3
,则可以将traffic_source_detail
值设为podcasts
,这表示流量是从播客目标网页引荐的。
2022 年 2 月 11 日
gender
维度的有效值集将于 2022 年 8 月 11 日当天或之后发生变化。这可能是对您的 API 实现做出的不向后兼容的更改。根据 YouTube API 服务的服务条款中向后不兼容的更改部分的规定,这项变更会在生效前六个月公布。请在 2022 年 8 月 11 日之前更新您的 API 实现方式,以确保无缝过渡到新的一组值。
具体更改如下:
- 在 YouTube Analytics(定位查询)API 中,
gender
维度目前支持两个值:female
和male
。在 2022 年 8 月 11 日当天或之后,该维度支持三个值:female
、male
和user_specified
。 - 在 YouTube Reporting (Bulk Reports) 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。
- 截至 2021 年 12 月 13 日,在 YouTube Analytics(定位查询)API 中,
averageViewDuration
和averageViewPercentage
指标均会排除循环片段流量。 - 截至 2021 年 12 月 13 日,YouTube Reporting (Bulk Reports) API 中的
average_view_duration_seconds
和average_view_duration_percentage
指标均会排除循环片段流量。
2022 年 2 月 2 日
此 YouTube Reporting (Bulk Reports) API 支持新的流量来源维度值,该值用于指明观看源自直播跳转:
- 在 YouTube Reporting (Bulk Reports) API 中,
traffic_source_type
维度支持值28
。
对于此流量来源类型,traffic_source_detail
维度用于指定观看者源自的频道 ID。
2020 年 9 月 23 日
此 YouTube Analytics(定位查询)API 和 YouTube Reporting(批量报告)API 都支持新的流量来源维度值,该值表示观看者是通过在 YouTube Shorts 观看体验中纵向滑动来引荐的:
- 在 YouTube Analytics API(定位查询)API 中,
insightTrafficSourceType
维度支持值SHORTS
。 - 在 YouTube Reporting (Bulk Reports) API 中,
traffic_source_type
维度支持值24
。
对于这种新的流量来源类型,系统不会填充流量来源详情维度(YouTube Analytics API 中的 insightTrafficSourceDetail
或 YouTube Reporting API 中的 traffic_source_detail
)。
2020 年 7 月 20 日
此更新涉及两项会影响 YouTube Analytics(分析)(定位查询)API 的更改:
- YouTube 数据分析报告组的大小上限已从 200 个实体增加到了 500 个。
reports.query
方法的filters
参数用于标识检索 YouTube 数据分析数据时应应用的过滤条件列表。该参数支持为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 日(即 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 天内的观看次数。
- 七天的观看者百分比可以用每天的观看次数乘以当天的观看者百分比,得到当天在观看视频时登录的观看者人数。然后,可以将整个时间段内的已登录观看者人数相加,然后除以该时间段内的总观看次数,从而得出整个时间段的观看者百分比。
- 由于系统可能会将同一观看者计算为不同日期的唯一身份观看者,因此无法计算七天的唯一身份观看者人数。不过,您或许可以使用
month
维度(而非30DayTotals
维度)来推断 30 天内的唯一身份观看者人数数据。请注意,month
维度是指日历月,而30DayTotals
维度则根据指定的开始日期和结束日期计算 30 天的时间段。
2019 年 6 月 27 日
此更新包含与 YouTube 数据分析(定位查询)API 有关的以下更改:
-
由于该 API 的第 1 版现已完全弃用,因此我们更新了相关文档以移除对该版本的引用,包括弃用通知以及介绍如何更新到版本 2 的迁移指南。
2018 年 11 月 1 日
此更新包含与 YouTube 数据分析(定位查询)API 有关的以下更改:
-
API 版本 1 现已弃用。如果您尚未更新 API 客户端,请尽快将其更新为使用 API 版本 2,以尽量减少服务中断。如需了解详情,请参阅迁移指南。
请注意,我们最初已于 2018 年 4 月 26 日公布了弃用时间表。
2017 年 9 月 17 日
此更新包含与 YouTube 数据分析(定位查询)API 有关的以下更改:
-
数据模型概览文档中新增的数据匿名化部分指出,当指标未达到特定阈值时,某些 YouTube 数据分析中的数据会受到限制。这种情况可能在多种情况下发生。实际上,这意味着在以下情况下,报告可能不会包含全部(或部分)数据:
-
某个视频或频道在指定时间段内的流量有限;
或
-
您所选过滤器或维度(例如流量来源或国家/地区)的值未达到特定阈值。
新部分还讨论了 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 (Bulk Reports) API 相关的以下更改:
- 以下变更目前预定于 2018 年 7 月生效,新政策在全球范围内适用于所有报告和报告作业。
-
更改之后,大多数 API 报告(包括回填报告)将在生成之日后保留 60 天。不过,包含历史数据的报告将在生成之日后保留 30 天。
在此公告之前,所有 API 报告均可在生成后的 180 天内使用。需要明确的一点是,此项政策变更生效后,超过 30 天的历史数据报告也将无法再通过该 API 访问。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
采用驼峰式大小写 (endDate
),而不是 v2 API 中的连字符。此更改使参数名称在整个 API 中保持一致,因为 API 用于创建和管理群组的方法已经为参数名称采用驼峰式大小写形式。- v2 API 不支持向 Google 的全球 HTTP 批量端点 (
www.googleapis.com/batch
) 发送批量请求。如果您在 v2 API 中发送批量请求,则需要改用端点https://youtubeanalytics.googleapis.com/v2
。
此外,一些 v1 功能不受 v2 API 的支持:
reports.query
方法不再支持alt
、quotaUser
和userIp
请求参数。- v2 API 未提供支持由对不同 API 的请求组成的批次的批处理端点。(不过,一批请求可能包含对同一 API 的不同方法的请求。)此次弃用并非特定于 YouTube Analytics API,因为 Google 即将在其所有 API 上弃用全球批处理端点。
- v2 API 不支持 JSON-RPC 协议,API v1 支持该协议。再次强调,此次弃用并非特定于 YouTube Analytics API。
- 该 API 的版本已从
-
注意:这是弃用公告。
API 版本 1 (v1) 现已弃用,相关支持会持续到 2018 年 10 月 31 日。在该日期之后,对 v1 API 的所有请求都将停止运行。因此,请务必在 2018 年 10 月 31 日之前升级到 API v2,以免通过该 API 访问 YouTube 数据分析数据时出现任何中断。
2018 年 2 月 21 日
本次更新包含对 YouTube 数据分析(定位查询)API 的以下更改:
- 观看者受众特征报告(根据观看者的年龄段和性别汇总观看统计信息)不再支持
youtubeProduct
维度,该维度可识别发生用户活动的 YouTube 服务。
2018 年 1 月 18 日
此更新包含以下更改:
-
YouTube Reporting API(批量报告)
operating_system
维度用于标识发生观看的设备的软件系统,现在支持以下值:25
:KaiOS
-
YouTube Analytics 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 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 Music86
:YouTube 游戏87
:YouTube Kids88
: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 查看这些收入数据:
-
该 API 支持以下收入相关指标:
adImpressions
cpm
estimatedAdRevenue
estimatedRedPartnerRevenue
estimatedRevenue
grossRevenue
monetizedPlaybacks
playbackBasedCpm
以下报告支持这些指标:
2017 年 3 月 17 日
此更新包含以下更改:
-
YouTube Analytics API 支持
redViews
和estimatedRedMinutesWatched
指标,这两个指标都与 YouTube Red 观看人数相关。事实上,2016 年 9 月 15 日所宣布的 YouTube Reporting API 已支持这两个指标。- “
redViews
”指标表示 YouTube Red 会员观看视频的次数。 estimatedRedMinutesWatched
指标表示 YouTube Red 会员观看视频的分钟数。
频道报告和内容所有者报告文档已更新,显示了哪些报告支持这两项新指标。已支持“
views
”和“estimatedMinutesWatched
”指标的所有报告均支持这些指标。 - “
2017 年 3 月 3 日
此更新包含以下更改:
-
YouTube Reporting API(批量报告)
-
更正了
date
维度的定义:该维度值指的是从太平洋时间凌晨 00:00 开始,到指定日期、月份和年份的晚上 11:59(太平洋时间)结束的时间段。根据不同的季节,太平洋时间可以是 UTC-7 或 UTC-8。虽然日期通常表示 24 小时的时间段,但向前调整时钟的日期表示 23 小时的时间段,而向后调整日期的日期表示 25 小时的时间段。(之前该文档指出,每个日期代表一个唯一的 24 小时时间段,并且太平洋时间始终为 UTC-8。)
请注意,这种更正并不代表实际 API 行为的更改。
operating_system
维度用于标识发生观看的设备的软件系统,现在支持以下值:22
:Tizen23
:Firefox24
:RealMedia
-
已删除“
content_owner_basic_a1
”报告类型的所有报告作业。自 2016 年 8 月 19 日起,这种类型的报告已被完全弃用,但之前生成的“content_owner_basic_a1
”报告在生成后的 180 天内仍可使用。因此,有些报告在 2017 年 2 月 19 日才可供访问。但是,由于报告不再可用,因此也不需要与报告关联的作业。
-
-
YouTube Analytics API(定位查询)
-
更正了对
time periods
相关维度的说明,以指出该维度值指的是从太平洋时间凌晨 00: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 日发布了这些报告的弃用公告。)
-
频道报告
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 日
此更新包含以下更改:
-
片尾画面报告
-
片尾画面尺寸
end_screen_element_type
:与统计信息相关联的片尾画面元素的类型。end_screen_element_id
:YouTube 用来唯一标识片尾画面元素的 ID。
片尾画面指标
注意:我们自 2016 年 5 月 1 日起才开始提供片尾画面指标数据。
end_screen_element_impressions
:片尾画面元素的总展示次数。每显示 1 个片尾画面元素,系统就会记录 1 次展示。end_screen_element_clicks
:片尾画面元素被点击的次数。end_screen_element_click_rate
:片尾画面元素的点击率。
-
以下报告已不再受支持,并已从文档中移除。每种报告都有较新版本。(我们于 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 年 8 月 10 日所宣布的那样,我们已支持引用相同数据的新指标。下表显示了已弃用的指标名称和新指标的名称:
已弃用的指标 新指标 adEarnings
estimatedAdRevenue
impressionBasedCpm
cpm
impressions
adImpressions
redPartnerRevenue
estimatedRedPartnerRevenue
- 每个视频的每月全球广告收入
- 每个国家/地区每个视频的每日广告收入
- 全球每月每个资产的广告收入
- 每个国家/地区每个资产的每日广告收入
- 版权主张(此报告不包含收入数据)
-
该 API 支持两个与 YouTube Red 观看情况相关的新指标:
red_views
:YouTube Red 会员观看视频的次数。red_watch_time_minutes
:YouTube Red 会员观看视频的分钟数。
-
该 API 可支持 20 种报告的新版本。所有新版本都支持新的
red_views
和red_watch_time_minutes
指标。对于每个报告,新报告类型 ID 中的数字都会比旧报告类型 ID 中的一个数字高。(如本修订历史记录的后续内容所述,这些报告的旧版本现已弃用。)例如,
channel_basic_a1
报告现已弃用,取而代之的是channel_basic_a2
报告。以下列表列出了新的报告类型 ID:
频道视频报告
内容所有者视频报告
内容所有者资产报告
-
注意:这是弃用公告。
请注意,如果您已经有创建上述任何旧版报告的作业,则需要为重命名的报告创建新作业。随着新报告版本的发布,以下报告版本也已弃用:
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 天内仍可使用。
-
content_owner_basic_a1
报告已完全弃用,并从文档中移除。YouTube 将不会再生成该类型的新报告,但已生成的报告在生成后的 180 天内仍可使用。content_owner_basic_a1
报告将替换为content_owner_basic_a2
报告,如 2016 年 5 月 19 日的修订历史记录条目中所述。 -
新发布的 YouTube API 服务的《服务条款》(以下简称“更新后的条款”),YouTube 工程和开发者博客对此进行了详细介绍,其中对当前《服务条款》进行了丰富全面的更新。除了将于 2017 年 2 月 10 日生效的更新版条款之外,本次更新还包含一些证明文件,说明了开发者必须遵守的政策。
如需了解完整的新文档,请参阅更新后的条款的修订历史记录。此外,如果后续对更新版条款或支持文档的更改,也会在修订历史记录中进行说明。您可以通过该文档中的链接订阅 RSS Feed,在其中列出修订历史记录中的更改。
-
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 秒的不可跳过视频广告,会在用户观看视频之前播放。
-
YouTube Analytics API(定位查询)
- 以下渠道报告支持的指标列表已更新,纳入了卡片指标。实际上,自 2016 年 6 月 28 日起,这些报告中就添加了对卡片指标的支持,相应日期的修订历史记录条目更详细地介绍了相关更改。报告包括:
- 美国各州的基本用户活动
- 美国各州特定时间段内的用户活动
- 用户活动(按省份)
- 用户活动(按订阅状态)
- 各省份的用户活动(按订阅状态划分)
- 热门视频(按州)
- 订阅或未订阅观看者最常看的视频
-
更正了频道观众黏度报告和内容所有者观众黏度报告中的过滤条件列表,以反映必须使用
video
过滤条件,而不支持group
过滤条件。之前,这两份报告的文档错误地指出,您可以使用这两个过滤条件之一检索报告,也可以同时使用两者都不使用过滤条件。
- 以下渠道报告支持的指标列表已更新,纳入了卡片指标。实际上,自 2016 年 6 月 28 日起,这些报告中就添加了对卡片指标的支持,相应日期的修订历史记录条目更详细地介绍了相关更改。报告包括:
-
YouTube Reporting API(批量报告)
- 在 API 概览中,我们将说明如何获取报告的下载网址的部分已更正,指出 YouTube 会在没有可用数据的日子生成可下载的报告。这些报告包含标题行,但不包含其他数据。此信息已于 2016 年 4 月 12 日在同一文档的报告特征部分更新。
- 更正了“
content_owner_asset_cards_a1
”报告中的维度列表,以反映该报告使用的是“card_id
”维度。之前,本文档错误地将维度名称列为card_title
。
-
我们更新了 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
”。但请注意,该指标仅显示在此次更新后将会弃用的两个报告中。如上所述,在这些报告的较新版本中,此指标已重命名为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 生成的任何报告都不支持这些维度。 -
该 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 会在三个月的时间内生成该类型的报告。例如,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 请求失败的几种其他原因。 -
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
。
-
- 在 YouTube Reporting API 中,
sharing_service
维度支持以下新值:82
:iOS 系统 activity 对话框83
:Google Inbox84
:Android Messenger
- 在 YouTube Analytics API 中,
sharingService
维度支持以下新值:ANDROID_MESSENGER
:Android MessengerINBOX
:Google InboxIOS_SYSTEM_ACTIVITY_DIALOG
:iOS 系统 activity 对话框
playback_location_type
维度支持两个新的维度值:7
:此数据与在 YouTube 首页或主屏幕、用户的“订阅”Feed 或其他 YouTube 浏览功能中获得的观看次数有关。8
:此数据与直接在 YouTube 搜索结果页上发生的观看有关。
traffic_source_type
维度现在支持使用18
作为维度值。此值表示视频观看次数源自列出播放列表中的所有视频的网页。此来源与来源类型14
不同,后者是指观看次数是在视频作为播放列表的一部分播放时发生的。insightPlaybackLocationType
维度支持两个新的维度值:BROWSE
:此数据与在 YouTube 首页或主屏幕、用户的“订阅”Feed 或其他 YouTube 浏览功能中获得的观看次数有关。SEARCH
:此数据与直接在 YouTube 搜索结果页上发生的观看有关。
insightTrafficSourceType
维度现在支持使用YT_PLAYLIST_PAGE
作为维度值。此值表示视频观看次数源自列出播放列表中的所有视频的网页。此来源与PLAYLIST
来源类型不同,后者表示观看次数是在视频作为播放列表的一部分播放时发生的。- 在 YouTube Reporting API 中,
operating_system
维度使用值21
标识通过 Chromecast 发生的观看。 - 在 YouTube Analytics API 中,
operatingSystem
维度使用值CHROMECAST
标识通过 Chromecast 发生的观看。 -
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、大陆、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
参数设置为该值以检索其他结果。 -
YouTube Analytics API 现在支持
redPartnerRevenue
指标,该指标可报告在所选报告维度下,通过 YouTube Red 订阅赚取的估算收入总额。该指标的值反映的是音乐和非音乐内容带来的收入,并且可能在月末进行调整。YouTube Analytics API 的内容所有者报告列表已更新,以找出支持
redPartnerRevenue
指标的视频报告: -
YouTube Analytics API 的热门视频报告定义现在反映此报告还支持以下收入指标:
earnings
、adEarnings
、grossRevenue
、monetizedPlaybacks
、playbackBasedCpm
、impressions
和impressionBasedCpm
。 -
我们更正了 YouTube Reporting API 中
date
维度的相关文档,以反映这些日期是指从太平洋时间午夜 12:00 (UTC-8) 开始的 24 小时时间段。之前,该文档指出该日期从午夜 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
属性的定义已全部更正,以指出属性值精确到微秒,而非纳秒。此外,所有定义现在都会准确反映属性值是时间戳。 -
YouTube Analytics API 的
sharingService
维度文档已更新,列出了可能的维度值。此列表包含许多新支持的服务。YouTube Reporting API 的
sharing_service
维度的定义也已更新,以列出新支持的值。大于59
的枚举值是列表中的新值。 -
新的 YouTube Reporting API 可以检索批量数据报告,其中包含频道或内容所有者的 YouTube 数据分析数据。它专为可导入大型数据集并提供工具,对这些数据进行过滤、排序和挖掘数据的应用而设计。
每个 YouTube Reporting API 报告都包含一组预定义的维度和指标。(YouTube Analytics API 报告也使用指标和维度。)在报告中,每一行数据都具有一个唯一的维度值组合。您可以根据维度值汇总各行的数据,以计算各个视频、国家/地区、直播视频、订阅用户等的指标。
您可以使用 API 安排报告作业,每个作业用于标识 YouTube 应生成的报告。设置任务后,YouTube 会生成可异步下载的每日报告。每个报告都包含 24 小时内的唯一数据。
-
虽然是不同的 API,但 YouTube Analytics API 和 YouTube Reporting API 都可让开发者检索 YouTube 数据分析数据。由于这两个 API 都提供对类似数据集的访问权限,因此这两个 API 的文档将作为一组文档发布。
-
为使 API 更易于理解,我们调整了 API 文档的结构。因此,以下变更并不涉及新功能:
-
现在,该文档包含两个页面:一个列出所有可用的频道报告,另一个列出所有可用的内容所有者报告。以前,相关文档针对频道视频报告、频道播放列表报告等分别提供了单独的页面。
-
新的数据模型概览旨在更清晰地介绍 API 的工作原理。具体而言,本文档旨在更好地解释 YouTube 如何使用指标、维度和过滤条件计算报告值。
-
用于检索报告的 API 的
reports.query
方法现已单独记录。该网页上的信息之前已在其他一些网页上显示。新页面旨在帮助您更轻松地找到检索报告时需要发送的信息。
-
-
新的“
adEarnings
”指标涵盖了 Google 出售的所有广告来源带来的总估算收入(净收入)。这不是核心指标。对于已支持earnings
指标的任何报告,该 API 均支持adEarnings
指标。此外,我们对“
earnings
”指标的定义进行了更正,指出该指标的值包括所有 Google 出售的广告来源以及非广告来源的总估算收入。之前,该指标的定义有误,即该指标仅包含来自广告来源的收入。 -
primaryAdGrossRevenue
指标已弃用。请改为使用grossRevenue
指标来检索收入数据。 -
除了已弃用的
primaryAdGrossRevenue
指标之外,广告效果报告不再支持monetizedPlaybacks
和playbackBasedCpm
指标。不过,有些视频报告仍然支持这些指标。 -
该 API 现在支持针对视频报告使用
videosAddedToPlaylists
和videosRemovedFromPlaylists
这两个新指标。我们更新了频道和内容所有者的视频报告列表,以找出支持这些新指标的报告。videosAddedToPlaylists
– 查询范围内的视频添加到任意 YouTube 播放列表的次数。这些视频可能已添加到视频所有者的播放列表或其他频道的播放列表中。videosRemovedFromPlaylists
– 从所有 YouTube 播放列表中移除查询范围内的视频的次数。相关视频可能已从视频所有者的播放列表或其他频道的播放列表中移除。
这两个指标都包含“稍后观看”播放列表之类的默认播放列表。但不会计入视频自动添加到的播放列表,例如频道的上传内容播放列表或用户的观看记录。另请注意,这些指标反映的是添加或删除的绝对数量。因此,如果用户将一个视频添加到播放列表,然后移除,然后重新添加,则这些指标会表明该视频已添加到两个播放列表,并从一个播放列表中移除。
这些指标的数据于 2014 年 10 月 1 日开始提供。
-
自本公告起,
favoritesAdded
和favoritesRemoved
指标已被弃用。这些指标都是核心指标,受服务条款中规定的弃用政策约束。 -
借助新的
currency
参数,您可以使用美元 (USD
) 以外的货币检索收入指标。如果已设置该参数,则 API 会将earnings
、grossRevenue
、playbackBasedCpm
和impressionBasedCpm
指标的值转换为指定币种。返回的值是根据每日变化的汇率计算得出的估算值。此参数值是由三个字母组成的 ISO 4217 货币代码。默认值为
USD
。该参数定义包含一系列支持的货币代码。 -
现在,该 API 支持创建和管理 YouTube 分析工具组,以及检索这些组的报告数据。
-
创建和管理群组
此更新引入了用于创建和管理群组的
group
和groupItem
资源。group
资源代表一个 Analytics(分析)群组,即最多包含 200 个频道、视频、播放列表或资产的自定义集合。对于此资源,API 支持list
、insert
、update
和delete
方法。groupItem
资源表示 Google Analytics(分析)组中的项目。对于此资源,API 支持list
、insert
和delete
方法。
例如,您可以使用
groups.insert
方法创建一个组,然后使用groupItems.insert
方法向该组添加项。 -
检索组的报告数据
维度文档已更新,现在包含
group
维度,该维度可用作许多频道报告和内容所有者报告的过滤条件。当您使用group
过滤条件时,API 会返回该组中所有项的数据。请注意,该 API 目前不支持为素材资源组创建报告。
如需详细了解 YouTube 数据分析组,请参阅 YouTube 帮助中心。
-
-
该 API 不再支持
show
维度。 -
API 现在支持为
video
、playlist
、channel
和show
维度指定多个值(当这些维度用作过滤条件时)。如需指定多个值,请将filters
参数值设为一个以英文逗号分隔的列表,其中包含应过滤 API 响应的视频、播放列表、频道或节目的 ID。此参数值最多可指定 200 个 ID。如果您为同一过滤条件指定了多个值,则也可以将该过滤条件添加到您为请求指定的维度列表中。即使相应过滤条件没有列为特定报告支持的维度,也是如此。如果您将过滤条件添加到维度列表,该 API 也会使用过滤条件值对结果进行分组。
如需详细了解此功能,请参阅
filters
参数定义。 -
检索渠道报告时,您现在可以通过将
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
报告。 -
内容所有者报告文档已更新,指出现在可以检索由内容所有者声明或上传的内容的
subscribersGained
和subscribersLost
指标。这项变化会显示在内容所有者的第一份基本统计信息报告中,该报告现在支持
claimedStatus
和uploaderType
过滤条件。 -
我们对示例请求文档进行了重新设计,按照类别对示例进行分组,所用的标签页格式与最近针对频道和内容所有者报告发布的标签格式类似。在新设计中,示例分为以下类别:
- 基本统计数据
- 基于时间
- 地理位置
- 播放位置
- 流量来源
- 设备/操作系统
- 受众特征
- 社交媒体
- 收入/广告(仅限内容所有者报告)
-
现在,请求示例文档中添加了在频道报告或内容所有者报告中检索省级行政区特定数据的新示例。
-
美国各州和华盛顿特区的省级指标:此报告会检索按省级行政区划分的频道视频的观看次数及其他统计信息。数据涵盖美国各州和华盛顿特区。该示例使用
province
维度,还使用filters
参数将响应限制为仅包含美国的搜索结果。 -
加利福尼亚州的观看者受众特征(年龄段和性别):此报告检索加利福尼亚州观看频道的视频的观看者的年龄段和性别的统计信息;对于内容所有者报告,此报告则会检索内容所有者已声明版权的内容。此示例使用
filters
参数确保响应仅包含特定省份的数据。
-
-
province
维度的定义已更新,以指出:当dimensions
参数值包含province
时,该请求还必须将数据限制到美国,方法是在filters
参数值中添加country==US
。 -
我们重新设计了列出受支持的频道和内容所有者报告的文档。每个文档都不会用表格列出所有可能的报告,而是将报告按类别分组:
- 基本统计数据
- 基于时间
- 地理位置
- 播放位置
- 流量来源
- 设备/操作系统
- 受众特征
- 社交媒体
- 热门视频
每个文档都会以标签列表的形式显示这些类别,您可以点击任意标签页以查看该类别中支持的报告。
-
该 API 现在支持三种新的地理位置维度:
province
、continent
和subContinent
。-
利用
province
维度,您可以检索美国各州和哥伦比亚特区的统计信息。对于此维度,该 API 支持两种用法: -
subContinent
维度指定联合国 (UN) 统计区域代码,用于标识相应大洲的次级区域。此维度只能用作过滤条件。由于每个子区域仅与一个大洲相关联,因此在使用
subContinent
过滤器时无需同时使用continent
过滤器。(事实上,如果请求同时使用这两个维度,API 会返回错误。)
-
-
文档已更正,因此
insightTrafficSourceDetail
维度不会将insightTrafficSourceType
值PROMOTED
添加为有效的过滤条件值。 -
YouTube Analytics API 现在需遵守服务条款中所述的弃用政策。不过,该 API 的非核心维度和非核心指标不受弃用政策的约束。维度和metrics页面已更新,现在可列出核心维度和指标。此外,这些页面上的定义已更新,明确指出核心维度和指标。
-
该 API 现在支持使用
EXTERNAL_APP
作为insightPlaybackLocationType
维度的值。随着这项更新推出,自 2013 年 9 月 10 日起,播放不再归类为MOBILE
播放,但在此日期之前发生的移动播放仍将按该值分类。经过此次更新,移动播放现在可归类为
WATCH
、EMBEDDED
或EXTERNAL_APP
播放,具体取决于发生播放的应用类型。 -
该 API 现在支持使用
PLAYLIST
作为insightTrafficSourceType
维度的值。该值表示视频观看次数源自播放列表。以前,应使用维度的YT_OTHER_PAGE
类别对这些视图进行分类。 -
该 API 现在支持按多个维度和指标对报告进行排序。示例请求文档包含一个新示例:按多个维度/指标对请求进行排序,该示例演示了此功能。请求会检索流量来源数据,并且
sort
参数值为day,-views
。结果按时间顺序排序,但在每天的结果集中,第一行包含观看次数最多的流量来源的数据,第二行包含观看次数第二高的来源的相关数据,以此类推。 -
该 API 现在支持
deviceType
和operatingSystem
这两个新维度,它们可用于检索观看者通过何种设备观看您的视频的数据。该 API 支持使用其中一个维度或两个维度的报告。-
通过
deviceType
报告,您可以获取不同类型设备(包括桌面设备、移动设备和平板电脑设备)的观看次数和估算观看时长。您还可以使用“operatingSystem
”过滤器将设备类型报告限制为仅包含运行特定操作系统(例如 Android 或 iOS)的设备的统计信息。 -
通过
operatingSystem
报告,您可以检索不同操作系统(例如 Android、iOS、Linux 等)的观看次数和估算观看时长。您还可以使用deviceType
过滤器限制操作系统报告,使其仅包含特定类型的设备(如移动设备或平板电脑)的统计信息。
-
-
示例请求文档已更新,现在包含 3 种针对频道的设备报告和 3 种针对内容所有者的设备报告。
-
“
insightPlaybackLocationType
”维度可能会返回值YT_OTHER
,该值用于标识未使用该维度的任一其他值分类的视图。 -
内容所有者报告文档已更新,指出您可以按收入的降序对热门视频报告进行排序,以找出收入最高的视频。此报告是“用户活动和收入报告”部分第二个表格中列出的第一种报告。
-
YouTube 不再标识实验性 API 功能和服务。我们现在改为提供受弃用政策约束的 YouTube API 的列表。
-
该 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
-
-
-
新的示例 API 请求文档提供了相关示例,演示了如何使用 YouTube Analytics API 获取多种不同的报告。每个示例都包含请求所提取报告的简要说明,然后显示该请求的维度、指标、过滤器和排序参数。
-
“
insightTrafficSourceType
”维度现在支持使用SUBSCRIBER
作为有效值。此值标识通过 YouTube 首页的 Feed 或 YouTube 订阅功能推荐的视频观看次数。如果您根据此流量来源进行过滤,insightTrafficSourceDetail
字段将会指明带来浏览的首页 Feed 或其他网页。 -
该 API 现在支持
annotationClickThroughRate
和annotationCloseRate
这两个新指标,这两个指标与观看者与视频中显示的注释的互动情况相关。我们更新了频道报告和内容所有者报告的列表,以找出支持这些新指标的报告。annotationClickThroughRate
- 观看者点击的注释与可点击注释的总展示次数的比率。annotationCloseRate
- 观看者关闭的注释与注释总展示次数的比率。
-
该 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 文档已经过重新整理,不同类型的报告分别对应到不同的页面。因此,我们现在在单独的页面中分别介绍了不同类型的频道报告和内容所有者报告。
-
现在,该 API 的参考指南中有一个示例部分,其中包含的代码示例演示了如何使用 Java、JavaScript、Python 和 Ruby 客户端库调用 API。JavaScript 代码示例与示例应用文档中详细讨论的代码示例相同。
-
API 参考指南现在介绍了 APIs Explorer,您可以通过它来调用 API、查看 API 请求以及检索响应中的实际数据。
-
该 API 支持多种适用于频道和内容所有者的新报告,如下所述。每种报告都可以提供频道报告或内容所有者报告。相应的维度和metrics页面也进行了相应更新。
-
播放位置报告指出不同类型的网页或应用上的视频观看次数。
-
播放位置详情报告会指出为特定视频带来最多观看次数的嵌入式播放器。通过识别与热门嵌入式播放器相关联的网址,它能够提供比播放位置报告更精细的视图。
-
流量来源报告可标识源自不同类型的引荐来源网址的视频观看次数。
-
流量来源详情报告可标识为特定视频和特定流量来源类型带来最多观看次数的引荐来源网址。例如,通过此报告,您可以查看为某个特定视频带来最多流量的相关视频。多个流量来源均支持此报告。
-
观看时长报告提供了观看者观看您的内容的时间长度。报告可以汇总特定时间范围(天、过去 7 天、过去 30 天等)或国家/地区的数据。如果报告按日期或国家/地区汇总数据,则还可以指定每次视频观看的平均时长以及用户观看的每个视频的平均百分比。
-
-
YouTube Analytics API 现已面向所有开发者发布。您可以通过 APIs console 中的服务面板为项目激活该 API,而无需先请求访问权限。
-
新的使用入门部分概述了构建使用 YouTube Analytics API 的应用时需满足的前提条件和基本步骤。
-
新增的了解配额使用情况部分提供了有关如何优化 API 配额使用情况的指南。API 服务器会计算每个请求的查询费用,这笔费用会从您的 API 使用配额中扣除。由于不同类型的报告可能具有截然不同的查询费用,因此您应该计划有效地使用配额,并且您的应用应仅请求其实际需要的指标和数据。
-
时间维度部分已更新,以说明这些维度指明 Google Analytics(分析)报告应根据特定时间段汇总数据。现在,该 API 还支持以下额外的时间维度:
7DayTotals
- 系统会对报告中的数据进行汇总,因此每行都包含七天的数据。30DayTotals
- 系统会对报告中的数据进行汇总,因此每行都包含 30 天的数据。month
– 报告中的数据将按日历月汇总。
同样,可用报告部分也已更新,以反映 API 对使用这些维度的报告的支持情况。
-
报告实体维度部分已作如下更新:用于检索内容所有者报告的 API 请求必须使用其中一个维度(
video
、channel
或show
)或受支持的claimedStatus
和uploaderType
维度组合来过滤数据。 -
该 API 现在支持适用于热门视频报告的两个新排序选项。这些报告以频道报告或内容所有者报告的形式提供,包含按国家/地区划分的指标(观看次数、评论数、赞的次数等),并按视频对这些指标进行细分。现在,您可以根据通过视频的观看页面订阅或取消订阅某个频道的用户数量,对这些报告进行排序。
-
我们更新了
subscribersGained
和subscribersLost
metrics的定义,以说明一个频道可能会在多个位置增加或减少订阅者,包括视频观看页面、频道页和 YouTube 首页上显示的导视面板。当这些指标显示在视频专用报告中时,这些指标只包含指定视频的观看页面中的统计信息。
YouTube Reporting API 支持三种新的片尾画面报告,以及适用于这些报告的新维度和指标。报告可提供视频停止播放后显示的片尾画面的展示和点击统计信息。
如需详细了解如何向视频添加片尾画面,请访问 YouTube 帮助中心。
2016 年 11 月 8 日
此更新包含对 YouTube Analytics(分析)API 的以下更改:
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 日
此更新包含以下更改:
2016 年 8 月 10 日
此更新包含以下变更:
2016 年 7 月 18 日
此更新包含以下变更:
2016 年 6 月 28 日
YouTube Analytics API 文档已更新,以反映众多频道和内容所有者报告中对卡片指标的支持。新增支持的指标包括:
以下类型的报告支持这些指标:
2016 年 6 月 22 日
本次更新包含以下 YouTube Reporting API 变更。第一个更改总体上与该 API 相关,其余更改仅影响内容所有者报告:
2016 年 5 月 19 日
本次更新包含以下 YouTube Reporting API 变更:
2016 年 4 月 12 日
此次更新包含以下更改,所有这些更改仅影响 YouTube Reporting API:
2016 年 3 月 28 日
YouTube Reporting API 和 YouTube Analytics API 现在会返回一些其他分享服务的观看统计信息。
2016 年 3 月 16 日
此次更新包含以下变更,对 YouTube Reporting API 和 YouTube Analytics API 都有影响:
YouTube 报告 API
YouTube Analytics API
2016 年 2 月 8 日
YouTube Analytics API 支持的指标列表已更新,因此卡片指标不再列为该 API 支持的指标。(该 API 的报告均未记录支持任何卡片指标。)
请注意,您仍然可以使用 YouTube Reporting API 检索卡片指标,该 API 支持众多频道和内容所有者报告中的这些指标。
2016 年 1 月 6 日
YouTube Reporting API 和 YouTube Analytics API 现在都可以专门识别通过 Chromecast 设备发生的观看。
2015 年 12 月 21 日
在该文档中,annotation_clickable_impressions
和 annotation_closable_impressions
指标的名称已更新,以与报告中返回的名称一致。之前,这两个名称记录为 clickable_annotation_impressions
和 closable_annotation_impressions
。
2015 年 12 月 18 日
根据欧盟法律规定,您必须向欧盟境内的最终用户提供特定披露声明并征得其同意。因此,对于欧盟境内的最终用户,您必须遵守欧盟地区用户意见征求政策。我们在 YouTube API 服务条款中添加了关于此要求的通知。
2015 年 12 月 15 日
此次更新包含以下变更,所有这些变更都会影响 YouTube Analytics API:
2015 年 11 月 10 日
此更新包含以下更改:
2015 年 10 月 29 日
此更新包含以下更改:
2015 年 10 月 8 日
此更新包含以下更改:
2015 年 9 月 24 日
此更新包含以下更改:
2015 年 8 月 20 日
此更新包含以下更改:
2015 年 7 月 22 日
此更新包含多项更改,所有更改均仅适用于内容所有者:
2015 年 6 月 1 日
此更新包含以下更改:
2015 年 3 月 31 日
此更新包含以下更改:
2015 年 3 月 16 日
此更新包含以下更改:
2015 年 2 月 25 日
此更新包含以下更改:
2015 年 2 月 13 日
此更新包含以下更改:
2014 年 8 月 28 日
此更新包含以下更改:
2014 年 7 月 16 日
此更新包含以下更改:
2014 年 1 月 31 日
此更新包含以下更改:
2014 年 1 月 16 日
此更新包含以下更改:
2014 年 1 月 6 日
此更新包含以下更改:
2013 年 9 月 30 日
此更新包含以下更改:
2013 年 7 月 16 日
此更新包含以下更改:
2013 年 5 月 23 日
此更新包含以下更改:
2013 年 5 月 10 日
此更新包含以下更改:
2013 年 5 月 6 日
此更新包含以下更改:
2013 年 5 月 3 日
此更新包含以下更改:
2013 年 3 月 28 日
此更新包含以下更改:
2013 年 3 月 21 日
此更新包含以下更改:
2013 年 2 月 4 日
此更新包含以下更改:
2012 年 11 月 14 日
此更新包含以下更改:
2012 年 10 月 2 日
此更新包含以下更改:
2012 年 9 月 12 日
此更新包含以下更改: