Dimensions

本文档定义了 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 检索这些 ID。

地理区域

这些维度用于标识与用户活动、广告效果或估算收入指标相关联的地理区域。

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（核心维度）
此维度用于标识与每个报告行中的指标相关联的日期。在批量报告中，日期是指从指定年、月、日的太平洋时间零点开始，到太平洋时间晚上 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 动态中的观看次数有关。
11 这些数据与竖屏直播推送中发生的观看有关。
12 这些数据与 YouTube Music“选段”标签页中的观看次数有关。
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。可能的值为：
值 说明
creator 创作者工作室
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 电视
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
32 VegaOS

受众特征

受众特征维度可帮助您了解受众群体的年龄段和性别分布情况。YouTube 帮助中心提供了有关 YouTube Analytics 报告中受众特征数据的更多信息。

age_group（核心维度）
此维度用于标识与报告数据关联的已登录用户的年龄段，包括 YouTube 估测未满 18 周岁的用户。该 API 使用以下年龄段：
  • AGE_13_17
  • AGE_18_24
  • AGE_25_34
  • AGE_35_44
  • AGE_45_54
  • AGE_55_64
  • AGE_65_
This is a core dimension and is subject to the Deprecation Policy.
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 Inbox
84 Android Messenger
85 YouTube Music
86 YouTube Gaming
87 YouTube Kids
88 YouTube TV
89 YouTube Watch with Friends
90 Allo
91 YouTube 社区帖子
92 YouTube 社区转发
93 KaiOS 消息
94 Google 地图复制/粘贴
95 与孩子分享
96 Web 系统活动对话框
97 Snapchat
98 预览从 YouTube Music 分享到 Snapchat 的内容
99 分享至 Snapchat 相机
100 Android 系统分享对话框
101 保存到设备上的相册中
102 Instagram
103 直接系统活动对话框
104 Discord
105 Instagram 快拍
106 Facebook 快拍
107 Meet 实时共享
108 三星信息
109 WhatsApp Business
110 三星笔记
111 Google Keep
112 Facebook Lite
113 IMO
114 YouTube Mango
115 Facebook 分享到群组
116 Google Chat
117 邀请播放列表协作者
118 快速分享
119 快速分享（三星）
120 已显示二维码
121 YouTube Shorts 绿幕
122 分享无广告体验
123 Google 应用
124 Google Chrome
125 盲盒反应
126 邀请链接 (Android)
127 邀请链接 (iOS)
128 混剪

如需了解详情，请参阅帮助文档。

注释

annotation_type
此维度用于标识注释在视频播放期间的显示方式。下表列出了可能的维度值：
值 说明
0 未知
1 注意
3 特别关注
4 标题
8 气泡
9 标签
10 品牌水印
11 精选视频
12 精选播放列表
30 号召性用语
YouTube 帮助中心提供了有关不同类型注释以及向视频添加注释的过程的更多详细信息。
annotation_id
YouTube 用于唯一标识注释的 ID。

卡片

card_type
此维度用于标识向用户显示的卡片类型。下表列出了可能的维度值：
值 说明
0 未知
60 链接
61 募捐筹款
62 视频
63 播放列表
65 粉丝打赏
66 商品
68 关联网站
69 渠道
YouTube 帮助中心提供了有关不同类型卡片的更多详细信息，以及向视频添加卡片的流程。
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
此维度用于标识观看期间使用时间最长的隐式字幕语言。如果观看者在观看视频时大多关闭了字幕，则这些观看次数不会计入。如需详细了解包含此维度的报告，请参阅频道报告或内容所有者报告的相关文档。
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 该行包含第三方上传的已声明版权的内容的数据。