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 参数值设置为以英文逗号分隔的视频、播放列表或频道 ID 列表，以便过滤 API 响应。参数值最多可指定 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 维度经常用于内容所有者报告中，因为这些报告通常会汇总多个频道的数据。
group （仅限过滤）
YouTube 数据分析组的 ID。您可以使用 YouTube Analytics API 的 groups.list 方法检索此值。使用 group 过滤条件时，API 响应会包含相应组中所有视频、播放列表或频道的数据。

示例

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

  • 频道示例

    • 基本统计信息
      • 前 10 名 - 频道的观看次数最多的视频
      • 前 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 国家/地区代码。此外，它也不支持美国以外的国家/地区的分区。

dma
Nielsen 用于标识与数据行中所述观看事件相关联的特定媒体市场区域 (DMA) 的 3 位数标识符。
city
与报告行中的指标相关联的估计城市。此维度的数据适用于 2022 年 1 月 1 日及之后的日期。
continent （仅限过滤）
联合国 (UN) 统计区域代码。该 API 支持以下值：
值
002 非洲
019 美洲（北美洲、拉丁美洲、南美洲和加勒比地区）
142 亚洲
150 欧洲
009 大洋洲
此维度只能用于过滤数据。如需使用此维度，请将 filters 参数的值设置为 continent==REGION_CODE，并指定表格中的 REGION_CODE 值。
subContinent （仅限过滤）
用于标识地理子区域的联合国统计区域代码。联合国统计司列出了各个次区域以及与每个区域相关联的国家/地区。

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

示例

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

  • 频道示例

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

  • 内容所有者示例

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

时间段

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

重要提示：所有日期均指从太平洋时间 (UTC-7 或 UTC-8) 凌晨 12:00 开始到太平洋时间晚上 11:59 结束的时间段，具体日期、月份和年份以指定为准。因此，时钟因夏令时而调快的时间段为 23 小时，而时钟调慢的时间段为 25 小时。

“月份”维度是指从指定月份和年份的第一天凌晨 12:00（太平洋时间，即 UTC-7 或 UTC-8）开始的时间段。

day （核心维度）
使用此维度时，报告中的数据会按天汇总，每行包含一天的数据。您还可以使用其他维度进一步细分数据。例如，流量来源报告可以根据用户观看视频的方式汇总每日观看统计信息。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 首页或主屏幕、用户的订阅动态或其他 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 应用（例如 YouTube Android 应用）中发生的观看次数。

  • YT_OTHER - 数据描述的是未归入其他类别的观看次数。

insightPlaybackLocationDetail
数据是根据播放器所在的网页汇总的。请注意，此报告仅支持在嵌入式播放器中发生的观看，并且会指明特定视频获得最多观看次数的嵌入式播放器。因此，它会识别与热门嵌入式播放器相关联的网址或应用，从而提供比播放位置报告更精细的视图。

示例

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

  • 频道示例

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

  • 内容所有者示例

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

播放详情

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

下表列出了维度值：
值
LIVE_STREAM 观看的内容是 YouTube 直播。
SHORTS 观看的内容是 YouTube 短视频。
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 日当天或之后。2021 年 3 月 1 日之前的数据包含在 CORE 中。系统不会记录实时数据。
UNKNOWN 用户活动发生在 2015 年 7 月 18 日之前。

流量来源

insightTrafficSourceType
报告中的数据是根据引荐来源类型汇总的，引荐来源类型描述了用户访问视频的方式。此维度的可能值包括：
  • ADVERTISING - 观看者是通过广告观看此视频的。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段会标识广告类型。
  • ANNOTATION - 观看者通过点击另一视频中的注释观看此视频。
  • CAMPAIGN_CARD - 指的是通过已声明版权的用户上传视频宣传观看内容而带来的观看次数。此流量来源仅适用于内容所有者报告。
  • END_SCREEN - 观看次数来自另一视频的片尾画面。
  • EXT_URL - 视频观看次数来自其他网站上的链接。如果您根据此流量来源进行过滤，insightTrafficSourceDetail 字段会标识网页。此流量来源包括来自 Google 搜索结果的引荐。
  • HASHTAGS - 观看次数来自视频点播主题标签页面或 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 首页上的动态或 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 - 将观看者吸引到报告中所述视频的首页动态项或 YouTube 订阅功能。有效值包括：
    • activity - 首页“订阅内容”动态中由非上传和非社交频道活动（包括赞、收藏、公告帖子和添加到播放列表）产生的观看次数。
    • blogged - 首页“订阅内容”动态中因热门博客中的链接而产生的观看次数。
    • mychannel - 首页上列出的其他动态（例如“赞过的视频”“观看历史记录”和“稍后观看”）中的内容带来的观看次数。
    • 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
  • AUTOMOTIVE
  • WEARABLE
  • 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.
gender（核心维度）
此维度用于标识与报告数据关联的已登录用户的性别。 有效值为 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
BlackBerry Messenger BBM
Blogger BLOGGER
复制到剪贴板 COPY_PASTE
Cyworld CYWORLD
Digg DIGG
Dropbox DROPBOX
嵌入 EMBED
电子邮件 MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook 主页 FACEBOOK_PAGES
Fotka FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
Go 短信 GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC 短信 HTC_MMS
Google Inbox INBOX
iOS 系统活动对话框 IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO Story KAKAO_STORY
Kakao (Kakao Talk) KAKAO
Kik KIK
LGE 电子邮件地址 LGE_EMAIL
折线图 LINE
LinkedIn LINKEDIN
LiveJournal LIVEJOURNAL
menéame MENEAME
mixi MIXI
Motorola 信息 MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
附近分享 NEARBY_SHARE
NUjij NUJIJ
Odnoklassniki (Одноклассники) ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
Rakuten（楽天市場） RAKUTEN
reddit REDDIT
Skype SKYPE
Skyrock SKYBLOG
Sony Conversations SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
短信 TEXT_MESSAGE
Tuenti TUENTI
tumblr。 TUMBLR
Twitter TWITTER
未知 UNKNOWN
Verizon 消息 VERIZON_MMS
Viber VIBER
VKontakte (ВКонтакте) VKONTAKTE
WeChat WECHAT
微博 WEIBO
WhatsApp WHATS_APP
Wykop WYKOP
Yahoo! 日本 YAHOO
YouTube 游戏 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。对于每个视频，在视频播放期间测量数据的时间点间隔相等。这意味着，对于时长为 2 分钟的视频，数据点之间的间隔为 1.2 秒。不过，对于时长为 2 小时的视频，数据点之间的间隔为 72 秒。相应维度的值表示区间的结束值（不含）。
audienceType （仅限过滤）
维度值用于标识与报告数据相关联的流量类型。 支持的值包括 ORGANIC、AD_INSTREAM 和 AD_INDISPLAY。如需了解这些流量来源类型的说明，请参阅 YouTube 帮助中心。

请注意，audienceType 过滤条件的数据自 2013 年 9 月 25 日起开始提供。对于使用过滤条件尝试检索更早日期的数据的查询，该 API 不会返回数据。不使用该过滤条件的查询适用于 2008 年 7 月 1 日之后的任何日期。

示例

以下示例请求使用了“受众群体留存情况”维度：

  • 频道示例

  • 内容所有者示例

直播

livestreamPosition
此维度用于指定直播视频流中的特定分钟。报告指标会显示当时有多少用户在观看直播。

会员资格取消

membershipsCancellationSurveyReason
在报告期内，已取消指定频道会员资格的 YouTube 用户完成的调查数量。下表列出了有效的维度值：
API 值 说明
UNKNOWN 用户未完成调查问卷。
DISLIKE_PERKS 用户不喜欢会员福利。
PERKS_NOT_DELIVERED 用户表示，承诺的会员福利未兑现。
CANNOT_ACCESS_PERKS 用户无法享受福利。
NO_LONGER_INTERESTED 用户不再对频道会员感兴趣。
FEEL_UNAPPRECIATED 用户认为自己作为频道会员未受到重视。
FINANCIAL_REASONS 用户因经济原因而取消。
JOIN_LIMITED_TIME 用户只想加入一段时间。
OTHER 用户因其他原因取消了订阅。

广告效果

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 - YouTube 无法对相应广告类型进行分类。

示例

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

  • 频道示例

    • 收入/广告
      • 频道收入和广告效果指标
      • 每日收入和广告效果指标
      • 特定国家/地区的收入和广告效果指标
      • 前 10 名 - 收入最高的视频
      • 不同广告类型的广告效果指标

  • 内容所有者示例

    • 收入/广告
      • 声明内容版权的视频的收入和广告效果指标
      • 每日收入和广告效果指标
      • 特定国家/地区的收入和广告效果指标
      • 前 10 名 - 收入最高的视频
      • 不同广告类型的广告效果指标

内容所有者维度

以下维度仅适用于内容所有者报告。

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

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

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

示例

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