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.
播放列表 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.
省份代码
与报告行中的指标相关联的美国州或地区。维度值是用于标识美国某个州或哥伦比亚特区的 ISO 3166-2 代码，例如 US-MI（密歇根州）或 US-TX（德克萨斯州）。省/直辖市/自治区代码 US-ZZ 用于报告 YouTube 无法识别关联的美国各州的指标。

注意：此维度不支持用于标识美国本土外地区的 ISO 3166-2 值，因为这些地区也有自己的 ISO 3166-1 国家/地区代码。也不支持细分除美国以外的国家/地区。

时间段

日期（核心维度）
此维度标识与每个报告行中的指标相关联的日期。对于批量报告，日期是指从太平洋时间零点凌晨 0: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 官方应用（例如 Android 版 YouTube 应用）中发生的活动相关。
1 这些数据与使用 <iframe> 或 <object> 嵌入视频的其他网站或应用中发生的活动相关。
2 这些数据与 YouTube 频道页发生的活动相关。
5 这些数据与无法归类到上面列出的其他地理位置类型的指标有关。
7 此数据涉及在 YouTube 首页或主屏幕上、用户的“订阅内容”动态或其他 YouTube 浏览功能中产生的观看次数。
8 这些数据与直接在 YouTube 搜索结果页上产生的观看次数有关。
10 这些数据与 YouTube Shorts 动态中的观看次数有关。
playback_location_detail
此维度指定播放的网址或应用。此维度仅适用于在嵌入式播放器中发生的观看，也就是说，只有维度值为 1 的行才会填充维度值。在其他行中，此维度的值为空。

播放详情

直播或点播
此维度用于指示数据行中的用户活动指标是否与直播的观看次数相关联。系统从 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 直播跳转
观看次数源自直播跳转。
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。

设备

设备类型
此维度标识了观看设备的实际外形规格。 下表列出了有效的维度值：
值
100 未知
101 计算机
102 TV
103 游戏机
104 手机
105 平板电脑
操作系统
此维度用于标识观看设备所在的软件系统。 下表列出了有效的维度值：
值
1 其他
2 Windows
3 Windows Mobile
4 Android
5 iOS
6 Symbian
7 黑莓
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_
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 《SumbleUpon》
6 mixi
7 Yahoo! 日本
8 goo
9 Ameba
10 Facebook
11 Myspace
12 努伊士语
18 图恩蒂语
20 Menéame
21 怀科普
22 高空滑索
25 福特卡
28 hi5
31 Twitter
32 土卫三
34 Blogger
36 VKontakte (ŞКонтакте)
37 乐天
38 LiveJournal
39 奥德诺拉斯拉斯尼
40 tumblr。
42 LinkedIn
43 Google+
44 微博
45 Pinterest
46 电子邮件
47 Facebook Messenger
49 WhatsApp
50 Hangouts
51 Gmail
52 片尾语（Kakao Talk）
53 其他
55 复制到剪贴板
59 嵌入
60 短信
61 Android 信息
62 Verizon 信息
63 HTC 短信
64 索尼对话
65 Go 短信
66 LGE 电子邮件
67 线
68 Viber
69 Kik
70 Skype
71 黑莓信使
72 微信
73 KAKAO 案例
74 Dropbox
75 Telegram
76 Facebook 主页
77 GroupMe
78 Android 电子邮件
79 Motorola Messaging
80 附近分享
81 Naver
82 iOS 系统活动对话框
83 Google 收件箱
84 Android Messenger
85 YouTube Music
86 YouTube Gaming
87 YouTube Kids
88 YouTube TV

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

注释

注解类型
此维度用于标识注释在视频播放期间的显示方式。下表列出了可能的维度值：
值
0 未知
1 注意
3 焦点
4 标题
8 气泡
9 标签
10 品牌水印
11 精选视频
12 精选播放列表
30 号召性用语
YouTube 帮助中心详细介绍了不同类型的注释，以及为视频添加注释的流程。
annotation_id
YouTube 用于唯一标识注释的 ID。

卡片

卡片类型
此维度可确定向用户显示的卡片类型。下表列出了可能的维度值：
值
0 未知
60 链接
61 募捐筹款
62 视频广告系列
63 播放列表
65 粉丝资助
66 商品
68 关联网站
69 （按频道）
YouTube 帮助中心详细介绍了不同类型的卡片，以及在视频中添加卡片的流程。
卡片 ID
YouTube 用于唯一标识卡片的 ID。

片尾画面

end_screen_element_type
此维度可确定向用户显示的片尾画面元素的类型。下表列出了片尾画面元素类型及其值：
值
501 视频 - 该元素宣传另一个 YouTube 视频。
502 播放列表 - 元素用于宣传 YouTube 播放列表。
503 网站 - 元素链接到关联的网站。
504 Channel - 元素链接到其他频道。
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。uploader_type 维度的定义中的表格提供了有关如何使用此维度的更多详细信息。
上传器类型（核心维度）（仅在内容所有者报告中使用）
此维度表示一行数据是否包含指定内容所有者上传的内容和/或第三方上传的内容（如用户上传的视频）的指标。有效值为 self 和 thirdParty。这是一个核心维度，受弃用政策的约束。

下表显示了 claimed_status 和 uploader_type 维度支持的组合：

claimed_status 值 uploader_type 值 说明
[未设置] 自身 该行包含内容所有者上传的已声明和未声明版权的内容的 YouTube 数据分析数据。
已声明 自身 该行包含内容所有者上传的已主张版权的内容的数据。
已声明 第三方 该行包含第三方上传的已声明版权的内容的相关数据。