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 上管理的资源：

注意：借助此 API，您可以为 video、playlist 和 channel 维度指定多个值，以便将其用作过滤条件。为此，请将 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 维度经常出现在内容所有者报告中，因为这些报告通常会汇总多个频道的数据。
group（仅限过滤条件）
YouTube 数据分析组的 ID。您可以使用 YouTube 数据分析 API 的 groups.list 方法检索此值。使用 group 过滤条件时，API 响应将包含该组中的所有视频、播放列表或频道的数据。

示例

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

  • 渠道示例

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

  • 内容所有者示例

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

地理区域

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

country（国家/地区）（核心维度）
与报告行中指标相关联的国家/地区。维度值是双字母 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 格式列出。

重要提示：所有日期都指从指定年月日的凌晨 12:00（太平洋时间，即 UTC-7 或 UTC-8）开始，到当天晚上 11:59（太平洋时间）结束的时间段。因此，当钟表向前调整为夏令时时，日期代表 23 小时的时间段；当钟表向后调整为夏令时时，日期代表 25 小时的时间段。

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

天（核心维度）
使用此维度时，报告中的数据会按天汇总，每行包含一天的数据。您可以使用其他维度进一步细分数据。例如，流量来源报告可以根据用户观看视频的方式汇总每日观看统计信息。This is a core dimension and is subject to the Deprecation Policy.
month（核心维度）
报告中的数据按日历月汇总。与每日报告一样，您可以使用其他过滤条件进一步细分数据。在报告中，日期以 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 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 中。CORE 包含 2021 年 3 月 1 日之前的数据。系统不会记录实时数据。
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 首页上的 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 - 将观看者引导至报告中涵盖的视频的首页动态项或 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
  • 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 信息 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 SMS GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC 短信 HTC_MMS
Google 收件箱 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 Messaging 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 Messages 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 维度的受支持组合来过滤数据。