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 数据分析 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 的美国热门播放列表

地理区域

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

国家/地区（核心维度）
与报告行中的指标相关联的国家/地区。维度值是两个字母的 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，并在联合国列表中指定 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.
月（核心维度）
报告中的数据按日历月汇总。与每日报告一样，您可以使用其他过滤条件进一步细分数据。报告采用 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 官方应用（例如 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 游戏中。
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 - 视频作为播放列表的一部分播放时产生的视频观看次数。请注意，此流量来源与 YT_PLAYLIST_PAGE 不同，后者表示观看次数源自列出播放列表中所有视频的页面。
  • 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_PLAYLIST_PAGE - 视频的观看次数来自列出播放列表中的所有视频的网页。请注意，此流量来源与 PLAYLIST 不同，后者表示观看次数是因视频在播放列表播放期间产生的。
  • YT_SEARCH - 观看者是通过 YouTube 搜索结果发现并观看视频的。如果您根据此流量来源进行过滤，则 insightTrafficSourceDetail 字段会指定搜索字词。
  • VIDEO_REMIXES - 观看者是通过 Shorts 播放器中的混剪视频链接推荐了视频。如果您根据此流量来源进行过滤，则 insightTrafficSourceDetail 字段会指定从何处引荐观看者。
insight TrafficSourceDetail
报告中的数据是根据引荐视频为指定视频和指定流量来源生成最多观看次数的引荐来源网址而汇总的。以下列表列出了提供此报告的流量来源。对于每个流量来源，该列表都会标识 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 - 首页订阅 Feed 中 uploaded 项内容的观看次数。
    • / – 源自 YouTube 首页的其他观看次数。
    • /my_subscriptions - 源自用户在 YouTube 上的我的订阅页面的观看次数。
  • YT_CHANNEL - 观看者观看视频所在的频道页。
  • YT_OTHER_PAGE - 其中引用了观看者的 YouTube 网页。
  • YT_SEARCH - 将观看者引导至视频的搜索字词。
  • VIDEO_REMIXES - 促成观看次数的视频。

示例

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

  • 频道示例

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

  • 内容所有者示例

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

设备

设备类型
此维度标识了观看设备的实际外形规格。 以下列表列出了 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 Messenger ANDROID_MESSENGER
Android 信息 ANDROID_MMS
黑莓信使 BBM
Blogger BLOGGER
复制到剪贴板 COPY_PASTE
土卫三 CYWORLD
Digg DIGG
Dropbox DROPBOX
嵌入 EMBED
电子邮件 MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook 主页 FACEBOOK_PAGES
福特卡 FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
Go 短信 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
Menéame MENEAME
mixi MIXI
Motorola Messaging MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
附近分享 NEARBY_SHARE
努伊士语 NUJIJ
奥德诺拉斯拉斯尼 ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
乐天 RAKUTEN
reddit REDDIT
Skype SKYPE
高空滑索 SKYBLOG
索尼对话 SONY_CONVERSATIONS
《SumbleUpon》 STUMBLEUPON
Telegram TELEGRAM
短信 TEXT_MESSAGE
图恩蒂语 TUENTI
tumblr。 TUMBLR
Twitter TWITTER
未知 UNKNOWN
Verizon 信息 VERIZON_MMS
Viber VIBER
VKontakte (ŞКонтакте) VKONTAKTE
微信 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 - 我们无法对此广告类型进行分类。

示例

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

  • 频道示例

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

  • 内容所有者示例

    • 收入/广告
      • 收到版权主张的内容的收入和广告效果指标
      • 每日收入和广告效果指标
      • 特定国家/地区的收入和广告效果指标
      • 前 10 大 – 收入最高的视频
      • 不同广告类型的广告效果指标

播放列表

isCurated（仅限过滤条件）
此过滤条件表示该请求检索的是在播放列表情境中发生的视频观看数据。任何播放列表报告都必须使用此过滤条件，且该参数的值必须设置为 1。

示例

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

内容所有者维度

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

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

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

claimedStatus 值 uploaderType 值 说明
[未设置] 自身 针对内容所有者上传的已声明版权和未声明版权的内容检索 YouTube 数据分析数据。
已声明 [未设置] 检索由内容所有者或第三方上传的已主张版权的内容的数据。
已声明 自身 检索由内容所有者上传的已声明所有权的内容的数据。
已声明 第三方 检索由第三方上传的已声明版权的内容的数据。

示例

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