Dimensions

本文档定义了 YouTube Analytics API 支持的维度。此 API 支持实时、有针对性的查询，以生成自定义的 YouTube 数据分析报告。

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

每个查询报告均标识了其支持的维度。例如，按时间检索用户活动时，您可以选择报告数据的时间段：天或月。在任何报告中，每一行数据都有唯一的维度值组合。

如需检索查询报告，请调用 YouTube Analytics API 的 reports.query 方法。在请求中，请使用 dimensions 参数指定 YouTube 将用于计算报告中的指标值的维度。

核心维度

虽然 YouTube Analytics API 需遵守服务条款中规定的弃用政策，但非核心维度（和非核心指标）不受此政策限制。在本页的定义中，任何属于核心维度的维度均明确标识为这样。

以下列表列出了该 API 的核心维度。

如需了解详情，请参阅受弃用政策约束的 YouTube API 列表。

滤镜

所有查询报告都支持过滤条件。过滤条件用于标识检索到的数据集中必须包含的维度值。因此，它们将 API 响应限制为仅包含与特定值或一组值匹配的数据。例如，您可以使用过滤器仅检索特定国家/地区的数据，而不是检索所有国家/地区的用户活动指标。

在检索查询报告的请求中，可选的 filters 请求参数指定要过滤其数据的维度值。例如，如需检索欧洲的用户活动指标，您可以将 filters 参数值设置为 continent==150。

重要提示：用于检索内容所有者报告的 API 请求必须使用其中一个报告实体维度或使用受支持的 claimedStatus 和 uploaderType 维度组合来过滤数据。

维度

以下各部分定义了 YouTube Analytics API 查询报告中使用的维度。除非另有说明，否则这些维度会同时用于频道报告和内容所有者报告。系统还会标识只能用作过滤条件的维度。

资源

这些维度对应的是频道和内容所有者在 YouTube 上管理的资源：

注意：当 video、playlist 和 channel 维度用作过滤条件时，您可以通过 API 为这些维度指定多个值。为此，请将 filters 参数值设为要过滤 API 响应的视频、播放列表或频道 ID 的列表（以英文逗号分隔）。此参数值最多可指定 500 个 ID。

视频 （核心维度）
YouTube 视频的 ID。在 YouTube Data API 中，这是 video 资源的 id 属性的值。This is a core dimension and is subject to the Deprecation Policy.
播放列表
YouTube 播放列表的 ID。在 YouTube Data API 中，这是 playlist 资源的 id 属性的值。
频道（核心维度）（仅用于内容所有者报告）
YouTube 频道的 ID。在 YouTube Data API 中，这是 channel 资源的 id 属性的值。This is a core dimension and is subject to the Deprecation Policy.

内容所有者报告中经常使用“channel”维度，因为这些报告通常会汇总多个频道的数据。
组（仅限过滤条件）
YouTube 数据分析组的 ID。您可以使用 YouTube Analytics API 的 groups.list 方法检索此值。当您使用 group 过滤条件时，API 响应包含该组中所有视频、播放列表或频道的数据。

示例

以下示例请求使用了报告实体维度或过滤条件：

  • 频道示例

    • 基本统计信息
      • 排名前 10 - 频道中观看次数最多的视频
      • 前 10 - 频道中观看次数最多的视频的注释点击率
      • 特定播放列表的统计信息
      • 前 10 - 频道中观看次数最多的播放列表
    • 地理位置
      • 排名前 10 - 特定国家/地区观看次数最多的视频
      • 10 大 - 欧洲观看次数最多的视频

  • 内容所有者示例

    • 基本统计信息
      • 内容所有者的前 10 大观看次数最多的视频
      • 10 大热门内容 - 某位内容所有者的观看次数最多的视频
      • 内容所有者频道中观看次数最多的 10 个视频
      • 前 10 - 频道中观看次数最多的视频的注释点击率
      • 前 10 - 某位内容所有者的观看次数最多的播放列表
    • 地理位置
      • 10 大热门内容 - 内容所有者在欧洲观看次数最多的视频
      • 十大 - 美国观看次数最多的播放列表

地理区域

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

国家/地区 （核心维度）
与报告行中的指标关联的国家/地区。维度值是两个字母的 ISO-3166-1 国家/地区代码，例如 US、CN（中国）或 FR（法国）。国家/地区代码“ZZ”用于报告 YouTube 无法识别其关联国家/地区的指标。This is a core dimension and is subject to the Deprecation Policy.
province
与报告行中的指标关联的美国州或地区。维度值是一个 ISO 3166-2 代码，用于标识美国的州或哥伦比亚特区，例如 US-MI（密歇根）或 US-TX（得克萨斯）。省代码 US-ZZ 用于报告 YouTube 无法识别其关联的美国州的指标。 当 API 请求的 dimensions 参数值包含 province 时，该请求还必须将数据限制为仅限美国使用，方法是在 filters 参数值中添加 country==US。

注意：此维度不支持用于标识美国本土外地区的 ISO 3166-2 值，因为这些地区还有自己的 ISO 3166-1 国家/地区代码。它也不支持美国以外的国家/地区的下属行政单位。

city
与报告行中的指标相关联的估算城市。系统提供自 2022 年 1 月 1 日起的此维度数据。
洲（仅限过滤条件）
联合国 (UN) 统计地区代码。该 API 支持以下值：
值
002 非洲
019 美洲（北美洲、拉丁美洲、南美洲和加勒比地区）
142 亚洲
150 欧洲
009 大洋洲
此维度只能用于过滤数据。如需使用此维度，请将 filters 参数的值设置为 continent==REGION_CODE，并指定上述列表中的 REGION_CODE 值。
subContinent（仅限过滤条件）
用于标识地理次级区域的联合国统计区域代码。联合国统计司会列出次级区域以及与每个区域关联的国家/地区。

此维度只能用于过滤数据。如需使用此维度，请将 filters 参数的值设置为 subContinent==REGION_CODE，并指定 UN 列表中的 REGION_CODE 值。

示例

以下示例请求使用地理位置维度或过滤条件：

  • 频道示例

    • 基本统计信息：频道在特定国家/地区的观看次数（及其他信息）
    • 地理位置
      • 频道视频在特定国家/地区的观看时长指标
      • 频道视频在特定国家/地区的注释指标
      • 美国各州和华盛顿特区的省级指标
      • 频道播放列表在特定国家/地区的观看时长指标
      • 十大 - 美国观看次数最多的播放列表
    • 播放位置：不同播放位置的每日观看次数和观看时长
    • 流量来源：一个国家/地区中不同流量来源的观看次数和观看时长
    • 受众特征：加利福尼亚州观看者受众特征（年龄段和性别）
    • 热门视频
      • 排名前 10 - 特定国家/地区观看次数最多的视频
      • 10 大 - 欧洲观看次数最多的视频

  • 内容所有者示例

    • 基本统计信息：所有自行上传的视频在特定国家/地区的观看次数（及其他数据）
    • 地理位置
      • 在特定国家/地区自行上传内容的观看时长指标
      • 针对自行上传内容的具体国家/地区注释指标
      • 美国各州和华盛顿特区的省级指标
      • 内容所有者的播放列表在特定国家/地区的观看时长指标
      • 十大 - 美国观看次数最多的播放列表
    • 播放位置：不同播放位置的每日观看次数和观看时长
    • 受众特征：加利福尼亚州观看者受众特征（年龄段和性别）
    • 热门视频：10 大 - 欧洲内容所有者观看最多的视频
    • 收入/广告效果：具体国家/地区的收入和广告效果指标

时间段

这些维度表示报表应按时间段（如一天、一周或一个月）汇总数据。startDate 和 endDate 请求参数用于指定报告包含的数据的时间段。请注意，该报告实际上会返回截至最后一天的数据，在该日期执行查询时，请求中指定的所有指标都可用。在报告中，日期以 YYYY-MM-DD 格式列出。

重要提示：所有日期都是指从指定日期、月份和日期的午夜 12:00（UTC-7 或 UTC-8）开始，到太平洋时间晚上 11:59 结束的时间段。因此，根据夏令时调整时钟的日期向前调整日期为 23 小时，向后调整时间的日期代表 25 小时的时间段。

月维度是指从指定月份和年份第一天的太平洋时间零点（UTC-7 或 UTC-8）开始的时间段。

天 （核心维度）
使用此维度时，报告中的数据会每天汇总一次，每行都包含一天的数据。您可以使用其他维度进一步细分数据。例如，流量来源报告可以根据用户访问您视频的方式汇总每日观看统计信息。This is a core dimension and is subject to the Deprecation Policy.
月 （核心维度）
此报告中的数据按日历月汇总。与每日报告一样，您可以使用其他过滤条件进一步细分数据。在报告中，日期以 YYYY-MM 格式列出。

注意：如果您的 API 查询使用 month 维度，则必须将 start-date 和 end-date 参数都设置为每月第一天。This is a core dimension and is subject to the Deprecation Policy.

示例

以下示例请求使用了时间维度或过滤条件：

  • 频道示例

    • 基于时间
      • 频道视频的每日观看时长指标
      • 频道视频的每日注释指标
      • 频道的每日播放列表观看次数
    • 播放位置：不同播放位置的每日观看次数和观看时长
    • 流量来源：不同流量来源带来的每日观看次数和观看时长
    • 设备/操作系统
      • Android 操作系统的每日设备类型指标
      • 移动设备的每日操作系统指标
      • 每日操作系统和设备类型指标

  • 内容所有者示例

    • 基于时间
      • 自行上传内容的每日观看时长指标
      • 已声明版权的内容的注解指标
      • 内容所有者的播放列表每日观看次数
    • 播放位置：不同播放位置的每日观看次数和观看时长
    • 流量来源：不同流量来源带来的每日观看次数和观看时长
    • 设备/操作系统
      • 已主张版权的视频的每日设备类型指标
      • 在移动设备上观看的已主张版权的视频的每日操作系统指标
      • 每日操作系统和设备类型指标
    • 收入/广告效果：每日收入和广告效果指标

播放位置

这些维度可让您深入了解发生用户活动的网页或应用。

insightPlaybackLocationType
此报告中的数据是根据发生视频播放的网页或应用的类型进行汇总的。此维度的可能值包括：

  • BROWSE - 此数据表示在 YouTube 首页或主屏幕、用户的“订阅”Feed 或其他 YouTube 浏览功能中获得的观看次数。

  • CHANNEL - 数据描述的是频道页上产生的观看次数。

  • EMBEDDED – 数据描述在使用 <iframe> 或 <object> 嵌入时嵌入了视频的其他网站或应用中产生的观看次数。

  • EXTERNAL_APP - 数据描述第三方应用中产生的观看次数，在该应用中，视频是使用 <iframe> 或 <object> 嵌入之外的方法播放的。例如，使用 YouTube Android Player API 的应用中的播放会使用此值进行分类。

  • MOBILE – 此数据描述的是发生在 YouTube 移动网站或已获批准的 YouTube API 客户端（包括移动设备）上的观看次数。

    自 2013 年 9 月 10 日起，YouTube 分析工具报告中不再将播放归类为MOBILE播放。由于旧数据仍然属于该类别，因此该值可能会保留在报告中。不过，在该日期之后，移动播放会被归类为 WATCH、EMBEDDED 或 EXTERNAL_APP 播放，具体取决于发生播放的应用的类型。

  • SEARCH - 此数据代表的是直接在 YouTube 搜索结果页上产生的观看次数。

  • WATCH – 此数据描述的是视频的 YouTube 观看页面或官方 YouTube 应用（如 Android 版 YouTube 应用）中产生的观看次数。

  • YT_OTHER - 数据描述未以其他方式分类的视图。

insightPlaybackLocationDetail
数据是根据玩家所在的网页进行汇总的。请注意，此报告仅适用于嵌入式播放器中出现的观看次数，可确定为特定视频带来最多观看次数的嵌入式播放器。因此，通过识别与顶级嵌入式播放器相关联的网址或应用，它能够提供比播放位置报告更精细的视图。

示例

以下示例请求使用了播放位置维度：

  • 频道示例

    • 播放位置
      • 不同播放位置的观看次数和观看时长
      • 不同播放位置的每日观看次数和观看时长
      • 排名前 10 - 为嵌入式视频带来最多观看次数的第三方网站
      • 来自不同播放位置的播放列表观看次数和观看时长
      • 不同播放位置的每日播放列表观看次数和观看时长

  • 内容所有者示例

    • 播放位置
      • 不同播放位置的观看次数和观看时长
      • 不同播放位置的每日观看次数和观看时长
      • 排名前 10 - 为嵌入式视频带来最多观看次数的第三方网站
      • 来自不同播放位置的播放列表观看次数和观看时长
      • 不同播放位置的每日播放列表观看次数和观看时长

播放详情

creatorContentType
此维度用于标识与数据行中的用户活动指标相关联的内容类型。系统从 2019 年 1 月 1 日开始提供此维度的数据。

下表列出了维度值：
值
LIVE_STREAM 观看的内容是 YouTube 直播。
SHORTS 观看的内容是 YouTube Shorts 短视频。
STORY 观看的内容是 YouTube 短片故事。
VIDEO_ON_DEMAND 观看的内容是不属于其他任一维度值的 YouTube 视频。
UNSPECIFIED 查看的内容的类型未知。
liveOrOnDemand
此维度用于指明数据行中的用户活动指标是否与直播观看次数相关联。系统从 2014 年 4 月 1 日开始提供此维度的数据。

下表列出了维度值：
值
LIVE 此行的数据描述了直播期间发生的用户活动。
ON_DEMAND 此行的数据描述了没有在直播期间发生的用户活动。
subscribedStatus
此维度用于指明数据行中的用户活动指标是否与订阅了视频或播放列表所属频道的观看者相关联。 可能的值包括 SUBSCRIBED 和 UNSUBSCRIBED。

请注意，维度值在用户活动发生时是准确的。例如，假设某个用户未订阅某个频道，并观看了该频道的一个视频，然后在同一天订阅了该频道并观看了另一个视频。 该频道的报告指出，一个观看的 subscribedStatus 值为 SUBSCRIBED，一个观看的 subscribedStatus 值为 UNSUBSCRIBED。
youtubeProduct
此维度用于标识发生了用户活动的 YouTube 服务。此维度的数据截至 2015 年 7 月 18 日。

下表列出了维度值：
值
CORE 未在某个特殊的 YouTube 应用（YouTube Gaming、YouTube Kids 或 YouTube Music）中发生的用户活动。例外情况：2021 年 3 月 1 日之前在 YouTube Music 中发生的用户活动会纳入CORE。
GAMING 该用户活动发生在 YouTube Gaming 中。
KIDS 该用户活动发生在 YouTube Kids 中。
MUSIC 用户活动发生在 2021 年 3 月 1 日或之后的 YouTube Music 中。2021 年 3 月 1 日之前的数据已包含在 CORE 中。系统不会记录实时数据。
UNKNOWN 用户活动发生在 2015 年 7 月 18 日之前。

流量来源

insightTrafficSourceType
报告中的数据根据引荐来源类型进行汇总，引荐来源类型说明了用户访问视频的方式。此维度的可能值包括：
  • ADVERTISING - 观看者是通过广告发现并观看视频的。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段用于标识通告的类型。
  • ANNOTATION – 观看者通过点击其他视频中的注释到达该视频。
  • CAMPAIGN_CARD – 观看次数来自已声明版权的用户上传视频（内容所有者使用这些视频来宣传观看的内容）。只有内容所有者报告支持此流量来源。
  • END_SCREEN – 观看源自另一个视频的片尾画面。
  • EXT_URL – 视频观看次数是通过其他网站的链接引荐到的。如果您根据此流量来源进行过滤，则 insightTrafficSourceDetail 字段会标识此网页。此流量来源包括来自 Google 搜索结果的引荐。
  • HASHTAGS – 来自 VOD 标签页面或 Shorts 标签转换页面的观看次数。
  • LIVE_REDIRECT - 视频观看次数来自直播跳转。
  • NO_LINK_EMBEDDED - 用户观看视频时，该视频被嵌入了其他网站。
  • NO_LINK_OTHER – YouTube 无法识别流量的引荐来源。此类别包括视频的直接流量以及移动应用获得的流量。
  • NOTIFICATION – 观看者是通过 YouTube 发送的电子邮件或通知发现的。
  • PLAYLIST – 视频观看次数是在视频作为播放列表的一部分播放时产生的。其中包括来自播放列表页面的流量。
  • PRODUCT_PAGE - 视频观看次数来自商品页面。
  • PROMOTED – 视频观看次数来自免费的 YouTube 宣传，例如 YouTube 的“热点视频”网页。
  • RELATED_VIDEO – 视频观看次数来自其他视频观看页面上的相关视频列表。如果您根据此流量来源进行过滤，则 insightTrafficSourceDetail 字段会指定该视频的视频 ID。
  • SHORTS – 在 Shorts 观看体验中，通过从上一个视频垂直滑动来推荐观看者。
  • SOUND_PAGE - 来自 Shorts 音效切换页面的观看次数。
  • SUBSCRIBER – 视频观看次数来自 YouTube 首页上的 Feed 或 YouTube 订阅功能。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段用于指定浏览来源的首页 Feed 项或其他页面。
  • YT_CHANNEL – 视频观看发生在频道页上。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段用于指定相应频道的频道 ID。
  • YT_OTHER_PAGE – 观看者是通过链接以外的链接观看视频的，而不是搜索结果或显示在 YouTube 页面上的相关视频链接。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段会标识该网页。
  • YT_SEARCH – 视频观看次数来自 YouTube 搜索结果。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段用于指定搜索字词。
  • VIDEO_REMIXES – 视频观看次数是通过 Shorts 短视频播放器中的混剪视频链接引荐到的。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段可用于指定观看者源自哪个视频。
insightTrafficSourceDetail
此报告中的数据是根据为指定的视频和指定的流量来源类型带来最多观看次数的引荐来源网址进行汇总的。以下列表列出了提供此报告的流量来源。对于每个流量来源，该列表都会标识出 insightTrafficSourceDetail 维度提供的信息。
  • ADVERTISING - 促成观看的广告类型。可能的值包括：
    • 点击播放互动广告
    • 互动广告
    • Google 搜索广告
    • 首页视频广告
    • 预留的可跳过的插播广告
    • TrueView 搜索广告和展示广告
    • TrueView 插播广告
    • 未分类的 YouTube 广告
    • 视频墙
  • CAMPAIGN_CARD – 已声明版权的视频，它将观看者引导至报告中指出的视频。
  • END_SCREEN – 将观看者引导至报告中指出的视频的视频。
  • EXT_URL - 将观看者引荐到视频的网站。
  • HASHTAGS - 促成浏览的 # 标签。
  • NOTIFICATION – 引荐流量的电子邮件或通知。
  • RELATED_VIDEO - 将观看者引导至报告中涵盖的视频的相关视频。
  • SOUND_PAGE - 带来观看次数的视频。
  • SUBSCRIBER – 将观看者引导至报告中涵盖的视频的首页 Feed 项或 YouTube 订阅功能。有效值包括：
    • activity – 由首页订阅 Feed 中由非上传和非社交频道活动（包括顶、收藏、公告和加入播放列表）产生的观看次数。
    • blogged – 由热门博客中的链接产生的首页订阅 Feed 中商品获得的观看次数。
    • mychannel - 由首页列出的其他 Feed 中的内容（例如“赞过的视频”“观看记录”和“稍后观看”）带来的观看次数。
    • podcasts - 由播客目标页面中的内容带来的观看次数。
    • sdig – 源自订阅更新电子邮件的观看次数。
    • uploaded - 由首页“订阅内容”动态中 uploaded 个条目带来的观看次数。
    • / – 源自 YouTube 首页的其他观看次数。
    • /my_subscriptions – 由 YouTube 上用户的我的订阅页面产生的观看次数。
  • YT_CHANNEL - 观看者观看视频的频道页。
  • YT_OTHER_PAGE - 观看者从中发现视频的 YouTube 网页。
  • YT_SEARCH - 将观看者引导至视频的搜索字词。
  • VIDEO_REMIXES - 带来观看次数的视频。

示例

以下示例请求使用的是流量来源维度：

  • 频道示例

    • 流量来源
      • 一个国家/地区中不同流量来源的观看次数和观看时长
      • 不同流量来源带来的每日观看次数和观看时长
      • 前 10 - 为视频带来最多流量的 YouTube 搜索字词
      • 前 10 - 为视频带来最多流量的 Google 搜索字词
      • 一个国家/地区中不同流量来源带来的播放列表观看次数和观看时长
      • 不同流量来源带来的每日播放列表观看次数和观看时长

  • 内容所有者示例

    • 流量来源
      • 不同流量来源的观看次数和观看时长
      • 不同流量来源带来的每日观看次数和观看时长
      • 前 10 - 为视频带来最多流量的 YouTube 搜索字词
      • 前 10 - 为视频带来最多流量的 Google 搜索字词
      • 一个国家/地区中不同流量来源带来的播放列表观看次数和观看时长
      • 不同流量来源带来的每日播放列表观看次数和观看时长

设备

deviceType
此维度用于标识观看事件的设备的实际外形规格。 以下列表列出了该 API 会返回数据的设备类型。您还可以使用“deviceType”维度作为过滤条件，限制操作系统报告仅包含特定类型的设备的数据。
  • DESKTOP
  • GAME_CONSOLE
  • MOBILE
  • TABLET
  • TV
  • UNKNOWN_PLATFORM
operatingSystem
此维度用于标识发生观看的设备的软件系统。 以下列表列出了该 API 会返回哪些操作系统的数据。您还可以使用 operatingSystem 作为过滤条件，将设备类型报告限制为仅包含特定操作系统的数据。
  • ANDROID
  • BADA
  • BLACKBERRY
  • CHROMECAST
  • DOCOMO
  • FIREFOX
  • HIPTOP
  • IOS
  • KAIOS
  • LINUX
  • MACINTOSH
  • MEEGO
  • NINTENDO_3DS
  • OTHER
  • PLAYSTATION
  • PLAYSTATION_VITA
  • REALMEDIA
  • SMART_TV
  • SYMBIAN
  • TIZEN
  • VIDAA
  • WEBOS
  • WII
  • WINDOWS
  • WINDOWS_MOBILE
  • XBOX

示例

以下示例请求使用了设备维度：

  • 频道示例

    • 设备/操作系统
      • Android 操作系统的每日设备类型指标
      • 移动设备的每日操作系统指标
      • 每日操作系统和设备类型指标
      • Android 操作系统上播放列表观看次数的每日设备类型指标
      • 移动设备上播放列表观看次数的每日操作系统指标

  • 内容所有者示例

    • 设备/操作系统
      • 已主张版权的视频的每日设备类型指标
      • 在移动设备上观看的已主张版权的视频的每日操作系统指标
      • 每日操作系统和设备类型指标
      • Android 操作系统上播放列表观看次数的每日设备类型指标
      • 移动设备上播放列表观看次数的每日操作系统指标

受众特征

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

ageGroup（核心维度）
此维度用于标识与报告数据关联的登录用户的年龄段。该 API 使用以下年龄段：
  • age13-17
  • age18-24
  • age25-34
  • age35-44
  • age45-54
  • age55-64
  • age65-
This is a core dimension and is subject to the Deprecation Policy.
性别 （核心维度）
此维度用于标识与报告数据关联的已登录用户的性别。 有效值为 female、male 和 user_specified。 This is a core dimension and is subject to the Deprecation Policy.

示例

以下示例请求使用了受众特征维度：

  • 频道示例

    • 受众特征
      • 加利福尼亚州的观看者受众特征（年龄段和性别）
      • 加利福尼亚州的播放列表观看者受众特征（年龄段和性别）

  • 内容所有者示例

    • 受众特征
      • 加利福尼亚州的观看者受众特征（年龄段和性别）
      • 加利福尼亚州的播放列表观看者受众特征（年龄段和性别）

互动度和内容分享

sharingService（核心维度）
此维度用于标识用于分享视频的服务。您可以使用“分享”按钮在 YouTube 上（或通过 YouTube 播放器）分享视频。This is a core dimension and is subject to the Deprecation Policy.

下表列出了有效的维度值：
分享服务 API 值
Ameba AMEBA
Android 电子邮件 ANDROID_EMAIL
Android 版 Messenger ANDROID_MESSENGER
Android 信息 ANDROID_MMS
黑莓 Messenger BBM
Blogger BLOGGER
复制到剪贴板 COPY_PASTE
赛世界 CYWORLD
Digg DIGG
Dropbox DROPBOX
嵌入地图 EMBED
Email MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook 主页 FACEBOOK_PAGES
福特卡 FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
启用短信 GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC 短信 HTC_MMS
Google 收件箱 INBOX
iOS 系统活动对话框 IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO 故事 KAKAO_STORY
卡考 (Kakao Talk) KAKAO
Kik KIK
LGE 电子邮件 LGE_EMAIL
折线图 LINE
LinkedIn LINKEDIN
LiveJournal LIVEJOURNAL
中东和北非 MENEAME
mixi MIXI
摩托罗拉消息功能 MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
附近分享 NEARBY_SHARE
NUjij NUJIJ
奥德诺克拉斯尼基（឵legacyоклассники） ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
乐天（楽天市场） RAKUTEN
reddit REDDIT
Skype SKYPE
天空石 SKYBLOG
索尼对话 SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
短信 TEXT_MESSAGE
图恩 TUENTI
tumblr. TUMBLR
Twitter TWITTER
未知 UNKNOWN
Verizon 信息 VERIZON_MMS
Viber VIBER
文塔克特语（估算值） VKONTAKTE
WeChat WECHAT
微博 WEIBO
WhatsApp WHATS_APP
怀科普 WYKOP
Yahoo! 日本 YAHOO
YouTube Gaming YOUTUBE_GAMING
YouTube Kids YOUTUBE_KIDS
YouTube Music YOUTUBE_MUSIC
YouTube TV YOUTUBE_TV

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

示例

以下示例请求使用的是社交维度：

  • 频道示例

    • 社交：分享指标，按分享视频的服务汇总

  • 内容所有者示例

    • 社交：分享指标，按分享视频的服务汇总

观众黏度

elapsedVideoTimeRatio
此维度指定视频的已播放部分与视频时长的比率。留存率维度和指标用于衡量一段时间内的观众黏度，elapsedVideoTimeRatio维度用于衡量时间长度。例如，如果值为 0.4，则表示相应的报告数据显示视频播完 40% 之后的黏度数据。

API 会为每个视频返回 100 个数据点，其比率值的范围为 0.01 到 1.0。在视频播放期间衡量数据的时间为每个视频分配相等的间距。也就是说，对于两分钟的视频，各数据点之间的时间间隔为 1.2 秒。而对于时长两小时的视频，数据点之间的时间间隔为 72 秒。维度的值表示区间的不含边界值。
audienceType （仅限过滤条件）
维度值用于标识与报告数据关联的流量类型。 支持的值包括 ORGANIC、AD_INSTREAM 和 AD_INDISPLAY。 有关这些流量来源类型的说明，请访问 YouTube 帮助中心。

请注意，audienceType过滤器的数据自 2013 年 9 月 25 日起已提供。如果查询使用过滤器尝试检索较早日期的数据，该 API 不会返回相应数据。不使用过滤条件的查询会应用于 2008 年 7 月 1 日之后的任何日期。

示例

以下示例请求使用的是观众黏度维度：

  • 频道示例

  • 内容所有者示例

广告效果

adType
广告效果报告中会使用 adType 维度，它会根据视频播放期间投放的广告类型汇总所请求的指标。 以下列表介绍了可能的维度值。如需详细了解 YouTube 广告格式，请参阅 YouTube 帮助中心。

  • auctionBumperInstream – 通过竞价方式投放的不可跳过的视频广告，时长不超过 6 秒钟，用户必须看完广告才能观看视频。

  • auctionDisplay – 一种富媒体或图片广告，在视频播放器底部叠加展示、在视频观看页面上显示为 300x250 广告单元，或兼而有之。叠加层运行时，会在显示一段时间后自动关闭，用户也可关闭叠加层。如果同时展示重叠式广告和横幅广告，则每个广告都会分别计为一次展示。

  • auctionInstream – 在主视频播放前、播放过程中或播放后展示的不可跳过的视频广告。

  • auctionTrueviewInslate - 观看者从视频播放前显示的一系列选项中选择其中一个视频广告。See the TrueView documentation for more information.

  • auctionTrueviewInstream – 在主视频播放前或播放过程中展示的可跳过视频广告。 如需了解详情，请参阅 TrueView 文档。

  • auctionUnknown – 通过 AdWords 竞价购买但尚未归入其他广告类型的广告。

  • reservedBumperInstream – 不可跳过的视频广告，以预订方式出售，时长不超过 6 秒钟，用户必须看完广告才能观看视频。

  • reservedClickToPlay - 用户必须点击才能开始播放的视频广告。无论用户是否启动播放，只要点击播放广告单元展示，系统就会记录一次广告展示。此类广告资源以预订方式出售。

  • reservedDisplay – 一种富媒体或图片广告，在视频播放器底部叠加展示、在视频观看页面上显示为 300x250 广告单元，或兼而有之。叠加层运行时，会在显示一段时间后自动关闭，用户也可关闭叠加层。如果同时展示重叠式广告和横幅广告，则每个广告都会分别计为一次展示。

  • reservedInstream – 在主视频播放前、播放过程中或播放后插入的不可跳过的视频广告。

  • reservedInstreamSelect

  • reservedMasthead – 显示在首页上的大型广告，可能包含视频和图形元素。

  • reservedUnknown - 以预留方式销售且无法分类为其他广告类型的广告。

  • unknown – 我们无法对此广告类型进行分类。

示例

以下示例报告会检索广告效果或收入指标：

  • 频道示例

    • 收入/广告
      • 频道收入和广告效果指标
      • 每日收入和广告效果指标
      • 特定国家/地区的收入和广告效果指标
      • 十大热门视频 - 收益最高的视频
      • 不同广告类型的广告效果指标

  • 内容所有者示例

    • 收入/广告
      • 已声明版权的内容的收入和广告效果指标
      • 每日收入和广告效果指标
      • 特定国家/地区的收入和广告效果指标
      • 十大热门视频 - 收益最高的视频
      • 不同广告类型的广告效果指标

播放列表

isCurated （仅限过滤条件）
此过滤条件表示请求正在检索在播放列表上下文中发生的视频观看次数的相关数据。

示例

所有检索播放列表报告的示例请求都使用 isCurated 过滤条件。

内容所有者维度

只有内容所有者报告支持以下维度。

重要提示：用于检索内容所有者报告的 API 请求必须使用以下维度之一来过滤数据：
  • video
  • channel
  • 受支持的 claimedStatus 和 uploaderType 维度组合（定义见下文）。
已声明所有权（仅用于内容所有者报告）
您可以使用此维度指明 API 响应应仅包含已声明版权的内容的指标。此维度的唯一有效值为 claimed。如果 filters 参数将查询限制为 claimedStatus==claimed，则该 API 将仅检索已声明版权的内容的数据。uploaderType 维度定义中的表格详细介绍了如何使用此维度。
UploaderType（核心维度）（仅用于内容所有者报告中）
借助此维度，您可以指明 API 响应是否应包含由指定的内容所有者上传的内容和/或由第三方上传的内容（如用户上传的视频）的指标。有效值为 self 和 thirdParty。这是一个核心维度，受弃用政策约束。

下表显示了支持在 filters 参数中使用的 claimedStatus 和 uploaderType 维度组合：

claimedStatus 值 uploaderType 值 说明
[未设置] 自己 检索内容所有者上传的已声明版权和未声明版权的内容的 YouTube 数据分析数据。
已声明 [未设置] 检索内容所有者或第三方上传的已声明版权的内容的相关数据。
已声明 自己 检索内容所有者上传的已声明版权的内容的数据。
已声明 thirdParty 检索第三方上传且已声明版权的内容的相关数据。

示例

许多针对内容所有者报告的示例 API 请求都会使用受支持的 claimedStatus 和 uploaderType 维度组合来过滤数据。