本文档定义了 YouTube Reporting API 支持的维度。此 API 用于检索包含面向频道或内容所有者的 YouTube 数据分析数据的批量报告。
维度是用于汇总数据的常用条件,例如用户活动发生的日期或用户所在的国家/地区。
每个批量报告都支持预定义的维度列表,并且在任何报告中,每行数据都有唯一的维度值组合。因此,每行的维度值组合都用作该行的主键。您无需指定报告中包含哪些维度,也无法指定。
核心维度
虽然 YouTube Reporting API 受服务条款中定义的弃用政策约束,但非核心维度(和非核心指标)不受该政策约束。在本页中的定义中,任何核心维度都会明确标识为核心维度。
以下列表列出了该 API 的核心维度。 所有这些维度也是 YouTube Analytics API 中的核心维度。
如需了解详情,请参阅符合弃用政策规定的 YouTube API 列表。
维度
以下部分定义了 YouTube Reporting API 批量报告中使用的维度。除非另有说明,否则这些维度同时用于频道和内容所有者报告。
资源
这些维度对应于频道和内容所有者在 YouTube 上管理的资源:
- video_id(核心维度)
- YouTube 视频的 ID。在 YouTube Data API 中,这是
video
资源的id
属性的值。This is a core dimension and is subject to the Deprecation Policy. - playlist_id
- YouTube 播放列表的 ID。在 YouTube Data API 中,这是
playlist
资源的id
属性的值。 - channel_id(核心维度)
- YouTube 频道的 ID。在 YouTube Data API 中,这是
channel
资源的id
属性的值。This is a core dimension and is subject to the Deprecation Policy. - asset_id(仅用于内容所有者报告)
- 在 YouTube 的 Content ID 系统中管理的资产的 ID。资产是指您的知识产权在该系统中的表现形式。在 YouTube 网站上,您可以在 YouTube 内容管理器中找到资产 ID。您还可以使用 YouTube Content ID API 检索这些信息。
地理区域
这些维度用于标识与用户活动、广告效果或估算收入指标相关的地理区域。
- country_code(核心维度)
- 与报告行中指标相关联的国家/地区。维度值是双字母 ISO-3166-1 国家/地区代码,例如
US
、CN
(中国)或FR
(法国)。国家/地区代码ZZ
用于报告 YouTube 无法识别关联国家/地区的指标。This is a core dimension and is subject to the Deprecation Policy. - province_code
- 与报告行中指标相关联的美国州或属地。维度值是用于标识美国各州或哥伦比亚特区的 ISO 3166-2 代码,例如
US-MI
(密歇根州)或US-TX
(德克萨斯州)。省级代码US-ZZ
用于报告 YouTube 无法识别关联的美国州级行政区的指标。注意:此维度不支持用于标识美国属地/海外领土的 ISO 3166-2 值,因为这些属地/海外领土也有自己的 ISO 3166-1 国家/地区代码。也不支持美国以外国家/地区的行政区划。
时间段
- date(核心维度)
- 此维度用于标识与每个报告行中指标相关联的日期。在批量报告中,日期是指从指定日、月、年的凌晨 12:00(太平洋时间)开始,到当天晚上 11:59(太平洋时间)结束的时间段。太平洋时间为 UTC-7 或 UTC-8,具体取决于季节。
请注意,虽然日期通常表示 24 小时的时间段,但当时钟向前调整为夏令时时,日期表示 23 小时的时间段;当时钟向后调整时,日期表示 25 小时的时间段。This is a core dimension and is subject to the Deprecation Policy.
播放位置
这些维度可提供有关用户活动发生的网页或应用的数据分析。
- playback_location_type
-
此维度用于识别用户活动发生的网页或应用的类型。下表列出了尺寸值:
值 0
这些数据与视频的 YouTube 观看页面或官方 YouTube 应用(例如 YouTube Android 应用)中发生的活动相关。 1
这些数据与使用 <iframe>
或<object>
嵌入的视频在其他网站或应用中发生的活动相关。2
这些数据与 YouTube 频道页面上发生的活动有关。 5
这些数据与无法归入其他列出地理位置类型的指标相关。 7
这些数据与在 YouTube 首页或主屏幕、用户的订阅动态或其他 YouTube 浏览功能中发生的观看次数有关。 8
这些数据与直接在 YouTube 搜索结果页上发生的观看次数有关。 10
这些数据与 YouTube Shorts 动态中的观看次数有关。 - playback_location_detail
- 此维度用于指定发生播放的网址或应用。此维度仅适用于嵌入式播放器中发生的观看,这意味着,只有在维度值为
1
的行中才会填充维度值。在其他行中,此维度的值为空。
播放详情
- live_or_on_demand
- 此维度表示数据行中的用户活动指标是否与直播观看次数相关联。系统会为 2014 年 4 月 1 日之后的日期提供此维度的数据。
下表列出了维度值:
值 live
该行的相关数据描述了直播期间发生的用户活动。 onDemand
该行的相关数据描述了未在直播期间发生的用户活动。 - subscribed_status
- 此维度表示数据行中的用户活动指标是否与订阅了视频或播放列表频道的观看者相关联。
可能的值有
subscribed
和unsubscribed
。
请注意,维度值在用户活动发生时是准确的。例如,假设某位用户未订阅某个频道,但观看了该频道的某个视频,然后在同一天订阅了该频道并观看了另一个视频。 频道的报告显示,其中一次观看的subscribed_status
值为subscribed
,另一次观看的subscribed_status
值为unsubscribed
。
流量来源
- traffic_source_type
- 此维度用于标识与用户活动指标相关联的引荐来源类型。引荐来源类型描述了用户到达与报告中数据行关联的视频或频道的途径。下表列出了尺寸值:
值 0
直接或不明来源
此值涵盖指向网页的直接流量,以及指向网页的来源未知的流量。在查询报告中,此类流量来源类型会标识为NO_LINK_OTHER
或UNKNOWN_MOBILE_OR_DIRECT
。1
YouTube 广告
观看者是通过广告找到的视频。在流量来源报告中,如果此维度的值为1
,则 traffic_source_detail 维度用于标识向观看者展示的广告类型。在查询报告中,此类流量来源被标识为ADVERTISING
。可能的值包括:值 ctp_engagement_ad
点击播放互动广告 engagement_ad
互动广告 googlemediaads
Google 搜索广告 insearch_display
TrueView 搜索广告和展示广告 instream
TrueView 插播广告 instream-select
预留的可跳过的插播广告 unknown
未分类的 YouTube 广告 video_wall
平铺视频 yva
首页视频广告 3
浏览功能
观看者是通过指向视频或频道的 YouTube 页面被引荐的。在流量来源报告中,如果此维度的值为3
,则 traffic_source_detail 维度会标识引荐流量的功能。在查询报告中,此类流量来源被标识为SUBSCRIBER
。可能的值包括:值 explore
儿童:探索 learning
儿童:学习 music
音乐 Feed my-history
观看记录 my-subscriptions
我的订阅 my-uploads
我上传的内容 podcasts
播客专属网页 shows
儿童:节目 watch-later
稍后观看 what-to-watch
精彩视频 4
YouTube 频道
观看者是通过 YouTube 频道页转来的。在流量来源报告中,如果此维度的值为4
,则 traffic_source_detail 维度会指定相应渠道的渠道 ID。在查询报告中,此类流量来源被标识为YT_CHANNEL
。5
YouTube 搜索
观看者是通过 YouTube 搜索结果找到您的视频的。在流量来源报告中,如果此维度的值为5
,则 traffic_source_detail 维度会指定关联的搜索字词。在查询报告中,此类流量来源被标识为YT_SEARCH
。7
推荐视频
观看者是从其他视频观看页面上的相关视频列表中转来的。在流量来源报告中,如果此维度的值为7
,则 traffic_source_detail 维度会标识相应视频的视频 ID。在查询报告中,此类流量来源类型会标识为RELATED_VIDEO
或YT_RELATED
。8
其他 YouTube 功能
观看者是通过不属于上述任何其他流量来源类型的 YouTube 页面引荐的。在流量来源报告中,如果此维度的值为8
,则 traffic_source_detail 维度会标识网页网址。在查询报告中,此类流量来源被标识为YT_OTHER_PAGE
。可能的值包括:值 g-crec
推荐频道 offline
离线 promotion
合作伙伴推广计划 unknown
未知 widget
Android 主屏幕微件 youtu.be
youtu.be ytremote
YouTube 遥控器 9
外部
:观看者是通过其他网站上的链接被引荐的。此流量来源包括来自 Google 搜索结果的引荐流量。在流量来源报告中,如果此维度的值为9
,则 traffic_source_detail 维度用于标识外部网页。在查询报告中,此类流量来源被标识为EXT_URL
。11
视频卡片和注释
观看者是通过点击其他视频中的注释或卡片而被引荐的。在查询报告中,此类流量来源被标识为ANNOTATION
。14
播放列表
视频作为播放列表的一部分播放时获得的观看次数。在查询报告中,此流量来源类型标识为PLAYLIST
。
请注意,此流量来源不同于来源类型18
,后者表示观看次数来自列出播放列表中所有视频的页面。17
通知
观看者是通过 YouTube 发送的电子邮件或通知被引荐的。在查询报告中,此类流量来源被标识为NOTIFICATION
。可能的值包括:值 inbox
push
sdig
由订阅者信息摘要中的通知带来的观看次数 uploaded_other
由在视频上传时发送给订阅者的非推送通知(例如电子邮件或收件箱通知)带来的观看次数 uploaded_push
在视频上传时向订阅者发送的推送通知带来的观看次数 18
播放列表页面
来自列出播放列表中所有视频的页面的观看次数。在查询报告中,此流量来源类型标识为YT_PLAYLIST_PAGE
。
请注意,此流量来源不同于来源类型14
,后者表示观看是在视频作为播放列表的一部分播放时发生的。19
涉及被指称侵权的内容的节目
来自被指称侵权的用户上传视频的观看次数,内容所有者使用这些视频来宣传所观看的内容。在查询报告中,此流量来源标识为CAMPAIGN_CARD
。此流量来源仅适用于内容所有者报告。20
互动式视频片尾画面
来自其他视频片尾画面的观看次数。在查询报告中,此类流量来源被标识为END_SCREEN
。23
短片故事
观看者是通过在短片故事观看体验中从上一个视频竖向滑动而被引荐的。24
Shorts
观看者是通过在 Shorts 观看体验中从上一个视频垂直滑动而被引荐的。25
商品页面
商品页面上的视频将观看者引导至其他频道。26
# 标签页面
来自 VOD # 标签页面或 Shorts # 标签跳转页面的观看次数。27
音效页面
来自 Shorts 音效跳转页面的观看次数。28
直播跳转
来自直播跳转的观看次数。29
播客
来自 YouTube 播客页面的观看次数。30
混剪视频
来自 Shorts 播放器中混剪视频链接的观看次数。31
竖屏直播推送
来自竖屏直播推送的观看次数。32
相关视频
通过 Shorts 短视频播放器中的相关视频链接获得的观看次数。 - traffic_source_detail
- 此维度可提供有关行traffic_source_type 维度值所代表的流量来源的更多详细信息。系统会为以下 traffic_source_type 维度值填充此维度值:
1
- 此维度值用于标识向观看者展示的广告类型。如需查看可能的值的列表,请参阅 traffic_source_type 定义。3
- 此维度值用于标识带来了引荐流量的 YouTube 功能。如需查看可能的值的列表,请参阅 traffic_source_type 定义。4
- 此维度值指定引荐观看者的频道 ID。5
- 维度值指定促成引荐流量的搜索字词。7
- 此维度值用于标识将观看者引导至相应广告的视频。8
- 此维度值用于标识带来了引荐流量的 YouTube 网页类型。如需查看可能的值的列表,请参阅 traffic_source_type 定义。9
- 此维度值用于标识流量来自的外部网页。17
- 此维度值用于标识促成引荐流量的通知类型。如需查看可能的值的列表,请参阅 traffic_source_type 定义。19
- 此维度值用于标识将观看者引导至相应广告的视频。20
- 此维度值用于标识将观看者引导至相应广告的视频。25
- 维度值用于标识商品 ID,即 Google 知识图谱 ID。26
- 此维度值用于标识带来了引荐流量的哈希标签。27
- 此维度值用于标识将观看者引导至相应广告的视频。28
- 此维度值指定了通过直播跳转引荐观看者的频道 ID。30
- 此维度值用于指定将观看者引导至相应视频的视频。
设备
- device_type
- 此维度用于标识发生观看的设备的外形规格。
下表列出了有效的尺寸值:
值 100
未知 101
计算机 102
TV 103
游戏机 104
手机 105
平板电脑 - operating_system
- 此维度用于标识发生观看的设备的软件系统。
下表列出了有效的尺寸值:
值 1
其他 2
Windows 3
Windows Mobile 4
Android 5
iOS 6
Symbian 7
Blackberry 9
Macintosh 10
PlayStation 11
Bada 12
WebOS 13
Linux 14
Hiptop 15
MeeGo 16
Wii 17
Xbox 18
PlayStation Vita 19
智能电视 20
任天堂 3DS 21
Chromecast 22
Tizen 23
Firefox 24
RealMedia 25
KaiOS 26
Roku 27
Nintendo Switch 28
Apple tvOS 29
Fire OS 30
ChromeOS 31
Vidaa
受众特征
受众特征维度可帮助您了解受众群体的年龄段和性别分布情况。YouTube 帮助中心提供了有关 YouTube Analytics 报告中受众特征数据的更多信息。
- age_group(核心维度)
- 此维度用于标识与报告数据关联的已登录用户的年龄段。该 API 使用以下年龄段:
AGE_13_17
AGE_18_24
AGE_25_34
AGE_35_44
AGE_45_54
AGE_55_64
AGE_65_
- gender(核心维度)
- 此维度用于标识与报告数据关联的已登录用户的性别。
有效值为
FEMALE
、MALE
和GENDER_OTHER
。 This is a core dimension and is subject to the Deprecation Policy.
互动和内容分享
- sharing_service(核心维度)
- 此维度用于标识用于分享视频的服务。您可以使用“分享”按钮在 YouTube 上(或通过 YouTube 播放器)分享视频。This is a core dimension and is subject to the Deprecation Policy.
下表列出了有效的尺寸值:
值 0
未知 1
Digg 4
reddit 5
StumbleUpon 6
mixi 7
Yahoo! 日本 8
goo 9
Ameba 10
Facebook 11
Myspace 12
NUjij 18
Tuenti 20
menéame 21
Wykop 22
Skyrock 25
Fotka 28
hi5 31
Twitter 32
Cyworld 34
Blogger 36
VKontakte (ВКонтакте) 37
Rakuten (楽天市場) 38
LiveJournal 39
Odnoklassniki (Одноклассники) 40
tumblr。 42
LinkedIn 43
Google+ 44
微博 45
Pinterest 46
电子邮件 47
Facebook Messenger 49
WhatsApp 50
Hangouts 51
Gmail 52
Kakao(Kakao Talk) 53
其他 55
复制到剪贴板 59
嵌入 60
短信 61
Android 信息 62
Verizon Messages 63
HTC 短信 64
Sony Conversations 65
Go SMS 66
LGE 电子邮件地址 67
折线图 68
Viber 69
Kik 70
Skype 71
BlackBerry Messenger 72
WeChat 73
KAKAO Story 74
Dropbox 75
Telegram 76
Facebook 页面 77
GroupMe 78
Android 电子邮件 79
Motorola Messaging 80
附近分享 81
Naver 82
iOS 系统活动对话框 83
Google 收件箱 84
Android 信息 85
YouTube Music 86
YouTube 游戏 87
YouTube Kids 88
YouTube TV
如需了解详情,请参阅帮助文档。
注释
- annotation_type
- 此维度用于标识注释在视频中显示的方式。下表列出了可能的尺寸值:
值 0
未知 1
备注 3
特别关注 4
标题 8
气泡 9
标签 10
品牌水印 11
精选视频 12
精选播放列表 30
号召性用语 - annotation_id
- YouTube 用于唯一标识注释的 ID。
卡片
- card_type
- 此维度用于标识向用户显示的卡片类型。下表列出了可能的尺寸值:
值 0
未知 60
链接 61
募捐筹款 62
视频 63
播放列表 65
粉丝赞助 66
商品 68
关联网站 69
频道 - card_id
- YouTube 用来唯一标识卡片的 ID。
片尾画面
- end_screen_element_type
- 此维度用于标识向用户显示的片尾画面元素的类型。下表列出了片尾画面元素类型及其值:
值 501
视频 - 该元素用于宣传其他 YouTube 视频。 502
播放列表 - 此元素用于宣传 YouTube 播放列表。 503
网站 - 此元素会链接到您的关联网站。 504
渠道 - 该元素会链接到其他渠道。 505
订阅 - 此元素可鼓励观看者订阅您的频道。 506
关联 507
众筹 - 此元素会链接到已获批准的众筹网站。 508
商品 - 此元素会链接到已获批准的商品网站。 509
近期上传的视频 - 此元素会链接到您频道中最近上传的视频。 510
最契合观看者兴趣的视频 - end_screen_element_id
- YouTube 用来唯一标识片尾画面元素的 ID。
字幕
- subtitle_language_autotranslated
- 此维度用于标识观看期间使用时间最长的自动翻译的字幕语言。系统不会统计字幕处于关闭状态的观看次数。如需详细了解包含此维度的报告,请参阅频道报告或内容所有者报告的文档。
广告效果
- ad_type
ad_type
维度用于广告效果报告,并会根据视频播放期间投放的广告类型汇总所请求的指标。 下表列出了可能的维度值。如需详细了解 YouTube 广告格式,请访问 YouTube 帮助中心。
值 说明 查询报告中的值 1
可跳过的视频广告(竞价) auctionTrueviewInstream
2
展示广告(竞价) auctionDisplay
3
不可跳过的视频广告(竞价) auctionInstream
5
展示广告(预留) reservedDisplay
6
不可跳过的视频广告(预留) reservedInstream
13
未知 unknown
15
可跳过的视频广告(预留) reservedInstreamSelect
19
导视广告(竞价) auctionBumperInstream
20
导视广告(预留) reservedBumperInstream
注意:查询报告可能会针对之前在 YouTube 上使用的某些其他广告类型返回结果。
内容所有者维度
以下维度仅用于内容所有者报告。
- claimed_status(仅用于内容所有者报告)
- 此维度表示一行数据仅包含已声明版权的内容的指标。此维度的唯一有效值为
claimed
。uploader_type
维度定义中的表格详细介绍了如何使用此维度。
- uploader_type(核心维度)(仅用于内容所有者报告)
- 此维度用于指明一行数据是否包含指定内容所有者上传的内容和/或第三方上传的内容(例如用户上传的视频)的指标。有效值为
self
和thirdParty
。这是核心维度,受弃用政策的约束。
下表显示了claimed_status
和uploader_type
维度的支持组合:
claimed_status
值uploader_type
值说明 [未设置] self 该行包含内容所有者上传的已声明版权和未声明版权的内容的 YouTube 数据分析数据。 已声明 self 该行包含内容所有者上传的收到版权主张的内容的数据。 已声明 thirdParty 该行包含第三方上传的被版权主张的内容的数据。