Introduction

本文介绍了 YouTube Analytics API 和 YouTube Reporting API 在访问 YouTube 数据分析数据的方式上存在的异同。本文档旨在帮助您选择适合自己的应用的 API。

开发者可以使用这两种 API 检索 YouTube 数据分析数据。此外,这两种 API 都支持 YouTube 频道所有者和 YouTube 内容所有者,他们各自都可以访问一组特定的报告:

  • 渠道报告包含指定渠道的用户活动指标。

  • 内容所有者报告会汇总与特定 YouTube 内容所有者相关联的所有频道的指标。例如,唱片公司可以检索包含唱片公司所有音乐人的 YouTube 频道的综合统计信息的报告。有些内容所有者报告包含用户活动指标,另一些报告则包含与收入和广告效果相关的指标。

部分内容所有者还可以使用 Reporting API 访问系统管理的广告收入报告。系统管理的报告中的数据只能通过 Reporting API 检索。

所有 YouTube 数据分析和 YouTube Reporting API 请求都必须获得所请求数据所属频道或内容所有者的授权。

报告内容

API 检索到的报告包含两种类型的数据:

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

    在报告中,每一行数据都有唯一的维度值组合。因此,每行的维度值组合都会充当该行的主键。

  • 指标是对用户活动、广告效果或估算收入的单独衡量结果。用户活动指标包括视频观看次数和评分(赞和踩的次数)等。

为您的应用选择合适的 API

YouTube Analytics API
YouTube Analytics API 支持实时定向查询,以生成自定义的 YouTube 数据分析报告。该 API 提供过滤和排序参数,因此发起调用的应用不需要原生支持这些函数。

每个 API 请求都会指定返回数据的日期范围。您还可以通过该 API 检索每周和每月数据集。因此,发起调用的应用不需要存储检索到的数据集,也不需要跨日期范围的汇总统计信息。
YouTube Reporting API
YouTube Reporting API 可以检索批量报告,其中包含频道或内容所有者的 YouTube 数据分析数据。它专为可导入大型数据集并提供用于对数据进行过滤、排序和挖掘所用工具的应用而设计。

每个报告都包含一组预定义的字段。开发者使用该 API 安排报告作业,每个作业用于标识 YouTube 应生成的报告。然后,YouTube 会生成一个可异步下载的每日报告。每个报告包含唯一 24 小时内的数据。

此外,YouTube 会自动为有权访问 YouTube 创作者工作室中相应报告的内容所有者生成一组由系统管理的报告。通过这些报告,您可以编程方式访问广告收入数据。

支持的报告

下表列出了您可以使用这些 API 检索的不同类型的报告。您可以通过 YouTube Analytics API 获取定位查询,通过 YouTube Reporting API 获取批量报告。

在一个 API 中可用的数据在另一个 API 中可能不可用。例如,YouTube Analytics API 允许您每周或每月检索用户活动指标,但 YouTube Reporting API 需要您自行汇总这些数据。另一方面,YouTube Reporting API 支持内容所有者的资产报告,但是 YouTube Analytics API 中不会提供这些数据。

报告类型
视频报告 支持频道(查询批量)和内容所有者(查询批量)。

视频报告提供与频道的视频或内容所有者的视频相关的所有用户活动的统计信息。例如,这些报告中包含您的视频获得的观看次数。在 YouTube Analytics API 中,一些内容所有者视频报告还包含估算收入和广告效果指标。
播放列表报告 支持频道(查询批量)和内容所有者(查询批量)。

播放列表报告会提供与播放列表中的视频观看次数特别相关的统计信息。YouTube Reporting API 支持针对播放列表生成观众黏度报告,但 YouTube Analytics API 不支持类似的报告。
广告效果报告 支持内容所有者(查询批量)。

广告效果报告可为视频播放期间投放的广告提供基于展示次数的指标。这些指标统计的是每次广告展示,并且每次视频播放可产生多次展示。
估算的收入报告 支持内容所有者(批量)。

估算收入报告提供了来自 Google 出售的广告来源和非广告来源的视频的估算总收入。这些报告还包含一些广告效果指标。请注意,系统管理的报表包含实际收入。
资产报告 支持内容所有者(批量)。

资产报告可提供与内容所有者的资产相关联的视频的用户活动指标。如果内容所有者已声明某视频与内容所有者的一项资产匹配,那么该视频就会被纳入内容所有者的报告中。该视频可能是由内容所有者或其他 YouTube 用户上传的。
系统管理的报告 适用于有权访问 YouTube 创作者工作室的“报告”菜单中的相应报告的内容所有者。

系统管理的报告可提供资产和视频产生的实际收入数据。另有一份报告列出了已主张版权的视频以及与这些视频匹配的资产。请注意,目前并非所有的创作者工作室报告都在 API 中提供。

注意:YouTube 会自动为有权访问创作者工作室中相应报告的内容所有者生成由系统管理的报告。因此,获取这些报告的过程与此列表中其他类型的报告不同。如需了解详情,请参阅系统管理的报告的相关文档。

主要区别

下表重点介绍了 YouTube Analytics(分析)API 和报告 API 之间的重要区别。

功能 YouTube Analytics API YouTube Reporting API
数据检索流程 每个 API 请求都会指定要返回的维度和指标,以及要返回数据的时间段。 应用安排报告作业。对于每项任务,YouTube 都会生成可异步下载的每日报告。
日期范围 有些 API 报告会指明用户活动发生的日期。其中部分报告支持按月汇总用户活动指标的维度。 所有 API 报告都会指明用户活动发生的日期。使用该 API 的应用可实现定期汇总数据的功能。
过滤数据 您可以对报告进行过滤,以便仅包含维度具有特定值的行。该 API 还支持某些仅用作过滤条件的维度,例如“大洲”和“次大陆”。subContinent 该 API 支持批量下载完整的数据集。它不支持对仅限过滤条件的维度进行过滤或返回数据。客户端应用存储下载的数据,并实现自己的功能来过滤数据。
排序 报告可以根据返回的指标值进行排序。某些报告仅支持有限数量的结果。例如,列出某个频道中观看次数最多的视频的报告最多会返回 200 行。 此 API 支持批量下载完整的数据集。客户端应用可以实现自己的功能,对下载的数据进行排序。
枚举 API 报告包含文本值(例如“ANDROID”或“CHANNEL”),用于标识枚举的维度值。 API 报告包含可映射到文本值的整数。
配额 API 服务器评估每个查询以确定其配额费用。配额使用情况部分更详细地介绍了这种方法。 配额使用量不是问题,因为数据只会检索一次,然后在应用中过滤、排序和查询。
唯一身份报告
  • 与字幕相关的用户活动
  • 播放列表的观众黏度数据
  • 面向内容所有者的估算收入报告(提供两种不同的报告)
  • 面向内容所有者的资产报告(提供 11 种不同的报告)
唯一维度 (仅限过滤条件的维度)
(仅限过滤条件的维度)
subContinent(仅限过滤条件的维度)

isCurated==1(仅限过滤条件的维度)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
独特指标 唯一身份用户数
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_partnerd_playlistsremove1}

estimated_partner_doubleclick_revenueplaylist_saves_addedplaylist_saves_removed

API 之间的命名差异

这两种 API 目前使用不同的命名惯例来识别维度和指标。目前,YouTube Analytics(分析)API 名称使用驼峰式大小写形式,而 YouTube Reporting API 名称则使用以下划线分隔的名称。

下表列出了这两种 API 用于标识相同指标和维度的不同名称。在某些情况下,两个名称之间的差异大于将名称从驼峰式大小写转换为下划线后得到的结果。例如,YouTube Analytics API 中的 video 维度在 YouTube Reporting API 中命名为 video_id

维度

YouTube 数据分析 API 名称 YouTube Reporting API 名称
adType ad_type
ageGroup age_group
资产 asset_id
audienceType audience_retention_type
channel channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
日期
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
gender [适用性别] gender [适用性别]
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
播放列表 playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
视频 video_id

指标

YouTube 数据分析 API 名称 YouTube Reporting API 名称
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
评论 评论
人踩 人踩
收入 estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
次展示 ad_impressions
顶的次数 顶的次数
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
股份 股份
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
次观看 次观看