Dimensions

This document defines the dimensions that the YouTube Reporting API supports. This API retrieves bulk reports that contain YouTube Analytics data for a channel or content owner.

Dimensions are common criteria that are used to aggregate data, such as the date on which user activity occurred or the country where users were located.

Each bulk report supports a predefined list of dimensions, and, in any report, each row of data has a unique combination of dimension values. As such, each row's combination of dimension values functions as the primary key for that row. You neither need to specify nor have the option of specifying which dimensions are included in the report.

Core dimensions

While the YouTube Reporting API is subject to the Deprecation Policy defined in the Terms of Service, non-core dimensions (and non-core metrics) are not subject to the policy. In the definitions on this page, any dimension that is a core dimension is explicitly identified as such.

The following list identifies the API's core dimensions. All of them are also core dimensions in the YouTube Analytics API.

• age_group
• channel_id
• country_code
• date
• gender
• sharing_service
• uploader_type
• video_id

For more information, see the list of the YouTube APIs subject to the Deprecation Policy.

Dimensions

The following sections define the dimensions that are used in the YouTube Reporting API's bulk reports. Unless otherwise noted, these dimensions are used in both channel and content owner reports.

Resources

These dimensions correspond to resources that channels and content owners manage on YouTube:

• video_id
• playlist_id
• channel_id
• asset_id

video_id (core dimension)

The ID of a YouTube video. In the YouTube Data API, this is the value of a video resource's id property. This is a core dimension and is subject to the Deprecation Policy.

playlist_id

The ID of a YouTube playlist. In the YouTube Data API, this is the value of a playlist resource's id property.

channel_id (core dimension)

The ID for a YouTube channel. In the YouTube Data API, this is the value of a channel resource's id property. This is a core dimension and is subject to the Deprecation Policy.

asset_id (only used in content owner reports)

The ID of an asset managed in YouTube's Content ID system. An asset is the representation of your intellectual property in that system. On the YouTube website, you can locate asset IDs in YouTube Content Manager. You can also retrieve them using the YouTube Content ID API.

Geographic areas

These dimensions identify a geographic region associated with user activity, ad performance, or estimated revenue metrics.

country_code (core dimension)

The country associated with the metrics in the report row. The dimension value is a two-letter ISO-3166-1 country code, such as US, CN (China), or FR (France). The country code ZZ is used to report metrics for which YouTube could not identify the associated country. This is a core dimension and is subject to the Deprecation Policy.

province_code

The U.S. state or territory associated with the metrics in the report row. The dimension value is an ISO 3166-2 code that identifies a U.S. state or the District of Columbia, such as US-MI (Michigan) or US-TX (Texas). The province code US-ZZ is used to report metrics for which YouTube could not identify the associated U.S. state.

Note: This dimension does not support ISO 3166-2 values that identify U.S. outlying areas since those territories also have their own ISO 3166-1 country codes. It also does not support subdivisions of countries other than the United States.

Time periods

date (core dimension)

This dimension identifies the date associated with the metrics in each report row. In bulk reports, the date refers to the period beginning at 12:00AM Pacific time and ending at 11:59PM Pacific time on the specified day, month, and year. Depending on the time of year, Pacific time is either UTC-7 or UTC-8.

Note that while dates typically represent a 24-hour period, dates when clocks are adjusted forward for Daylight Savings Time represent a 23-hour period, and dates when clocks are adjusted backward represent a 25-hour period. This is a core dimension and is subject to the Deprecation Policy.

Playback locations

These dimensions provide insight about the page or application where user activity occurred.

playback_location_type

This dimension identifies the type of page or application where user activity occurred. The following table lists dimension values:

Value	Description
0	The data pertains to activity that occurred on the video's YouTube watch page or in an official YouTube application, such as the YouTube Android app.
1	The data pertains to activity that occurred on another website or application where the video was embedded using an <iframe> or <object> embed.
2	The data pertains to activity that occurred on a YouTube channel page.
5	The data pertains to metrics that cannot be classified into one of the other listed location types.
7	The data pertains to views that took place on the YouTube home page or home screen, in the user's subscription feed, or in another YouTube browsing feature.
8	The data pertains to views that took place directly on the YouTube search results page.
10	The data pertains to views that took place on the YouTube Shorts feed.

playback_location_detail

This dimension specifies the URL or application where the playback occurred. This dimension is only supported for views that occurred in embedded players, which means that the dimension value is only populated in rows where the dimension's value is 1. In other rows, this dimension's value is empty.

Playback details

live_or_on_demand

This dimension indicates whether the user activity metrics in the data row are associated with views of a live broadcast. Data for this dimension is available for dates beginning April 1, 2014.

The following table lists dimension values:

Value	Description
live	The row's data describes user activity that occurred during a live broadcast.
onDemand	The row's data describes user activity that did not occur during a live broadcast.

subscribed_status

This dimension indicates whether the user activity metrics in the data row are associated with viewers who were subscribed to the video's or playlist's channel. Possible values are subscribed and unsubscribed.

Note that the dimension value is accurate as of the time that the user activity occurs. For example, suppose a user has not subscribed to a channel and watches one of that channel's videos, then subscribes to the channel and watches another video, all on the same day. The channel's report indicates that one view has a subscribed_status value of subscribed, and one view has a subscribed_status value of unsubscribed.

Traffic sources

traffic_source_type

This dimension identifies the referrer type associated with the user activity metrics. The referrer type describes the manner in which users reached the video or channel associated with the row of data in the report. The following table lists dimension values:

Value	Description
0	Direct or unknown This value encompasses direct traffic to a page as well as pages for which the referrer is unknown. In query reports, this traffic source type is identified as NO_LINK_OTHER or UNKNOWN_MOBILE_OR_DIRECT.
1	YouTube advertising The viewer was referred to the video by an advertisement. In a traffic source report, if this dimension's value is 1, then the traffic_source_detail dimension identifies the type of advertisement that was shown to the viewer. In query reports, this traffic source type is identified as ADVERTISING. Possible values are: Value Description ctp_engagement_ad Click-to-play engagement ad engagement_ad Engagement ad googlemediaads Google Search ads insearch_display TrueView in-search and in-display instream TrueView in-stream instream-select Reserved skippable in-stream unknown Uncategorized YouTube advertising video_wall Video wall yva Homepage video ad
3	Browse features The viewer was referred from a YouTube page that leads to videos or channels. In a traffic source report, if this dimension's value is 3, then the traffic_source_detail dimension identifies the feature that referred the traffic. In query reports, this traffic source type is identified as SUBSCRIBER. Possible values are: Value Description explore Kids: explore learning Kids: learning music Music feed my-history Watch history my-subscriptions My subscriptions my-uploads My uploads podcasts Podcasts destination page shows Kids: shows watch-later Watch later what-to-watch What to watch
4	YouTube channels Viewers were referred from a YouTube channel page. In a traffic source report, if this dimension's value is 4, then the traffic_source_detail dimension specifies the channel ID for that channel. In query reports, this traffic source type is identified as YT_CHANNEL.
5	YouTube search Viewers were referred from YouTube search results. In a traffic source report, if this dimension's value is 5, then the traffic_source_detail dimension specifies the associated search term. In query reports, this traffic source type is identified as YT_SEARCH.
7	Suggested videos Viewers were referred from a related video listing on another video watch page. In a traffic source report, if this dimension's value is 7, then the traffic_source_detail dimension identifies the video ID for that video. In query reports, this traffic source type is identified as RELATED_VIDEO or YT_RELATED.
8	Other YouTube features Viewers were referred from a YouTube page that does not fall into one of the other listed traffic source types. In a traffic source report, if this dimension's value is 8, then the