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.
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 (core dimension)
- The ID of a YouTube video. In the YouTube Data API, this is the value of a
video
resource'sid
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'sid
property. - channel_id (core dimension)
- The ID for a YouTube channel. In the YouTube Data API, this is the value of a
channel
resource'sid
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), orFR
(France). The country codeZZ
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) orUS-TX
(Texas). The province codeUS-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:
Values 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:
Values 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
andunsubscribed
.
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 asubscribed_status
value ofsubscribed
, and one view has asubscribed_status
value ofunsubscribed
.
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:
Values 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 asNO_LINK_OTHER
orUNKNOWN_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 is1
, 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 asADVERTISING
. Possible values are:Values 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 is3
, then the traffic_source_detail dimension identifies the feature that referred the traffic. In query reports, this traffic source type is identified asSUBSCRIBER
. Possible values are:Values 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 is4
, then the traffic_source_detail dimension specifies the channel ID for that channel. In query reports, this traffic source type is identified asYT_CHANNEL
.5
YouTube search
Viewers were referred from YouTube search results. In a traffic source report, if this dimension's value is5
, then the traffic_source_detail dimension specifies the associated search term. In query reports, this traffic source type is identified asYT_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 is7
, then the traffic_source_detail dimension identifies the video ID for that video. In query reports, this traffic source type is identified asRELATED_VIDEO
orYT_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 is8
, then the traffic_source_detail dimension identifies the page URL. In query reports, this traffic source type is identified asYT_OTHER_PAGE
. Possible values are:Values g-crec
Recommended channels offline
Offline promotion
Partner promotion unknown
Unknown widget
Android homescreen widget youtu.be
youtu.be ytremote
YouTube Remote 9
External
Viewers were referred from a link on another website. This traffic source includes referrals from Google Search results. In a traffic source report, if this dimension's value is9
, then the traffic_source_detail dimension identifies the external web page. In query reports, this traffic source type is identified asEXT_URL
.11
Video cards and annotations
Viewers were referred by clicking on an annotation or card in another video. In query reports, this traffic source type is identified asANNOTATION
.14
Playlists
Views occurred while the video was being played as part of a playlist. In query reports, this traffic source type is identified asPLAYLIST
.
Note that this traffic source differs from source type18
, which indicates that the views originated from the page that lists all of the videos in the playlist.17
Notifications
Viewers were referred from an email or notification from YouTube. In query reports, this traffic source type is identified asNOTIFICATION
. Possible values are:Values inbox
push
sdig
Views originated from notifications that were part of the subscriber digest uploaded_other
Views originated from non-push notifications, such as email or Inbox notifications, sent to subscribers when a video was uploaded uploaded_push
Views originated from push notifications sent to subscribers when a video was uploaded 18
Playlist pages
Views originated from a page that lists all of the videos in a playlist. In query reports, this traffic source type is identified asYT_PLAYLIST_PAGE
.
Note that this traffic source differs from source type14
, which indicates that the views occurred while the video was being played as part of a playlist.19
Programming from claimed content
Views originated from claimed, user-uploaded videos that the content owner used to promote the viewed content. In query reports, this traffic source is identified asCAMPAIGN_CARD
. This traffic source is only supported for content owner reports.20
Interactive video endscreen
Views originated from the endscreen of another video. In query reports, this traffic source type is identified asEND_SCREEN
.23
Stories
The viewer was referred by swiping vertically from the previous video in the Stories viewing experience.24
Shorts
The viewer was referred by swiping vertically from the previous video in the Shorts viewing experience.25
Product Pages
Videos on a product page brought viewers to another channel.26
Hashtag Pages
Views originated from VOD hashtag pages or Shorts hashtag pivot pages.27
Sound Pages
Views originated from Shorts sound pivot pages.28
Live redirect
Views originated from Live Redirects.30
Remixed video
Views originated from a remixed video link in the Shorts player.31
Vertical live feed
Views originated from the vertical live feed.32
Related video
Views originated from a related video link in the Shorts player. - traffic_source_detail
- This dimension provides additional detail about the traffic source that the row's traffic_source_type dimension value. This dimension value is populated for the following traffic_source_type dimension values:
1
– The dimension value identifies the type of advertisement that was shown to the viewer. See the traffic_source_type definition for a list of possible values.3
– The dimension value identifies the YouTube feature that led to the referred traffic. See the traffic_source_type definition for a list of possible values.4
– The dimension value specifies the channel ID from which the viewer was referred.5
– The dimension value specifies the search term that led to the referred traffic.7
– The dimension value identifies the video from which the viewer was referred.8
– The dimension value identifies the type of YouTube page that led to the referred traffic. See the traffic_source_type definition for a list of possible values.9
– The dimension value identifies the external page from which the traffic was referred.17
– The dimension value identifies the type of notification that led to the referred traffic. See the traffic_source_type definition for a list of possible values.19
– The dimension value identifies the video from which the viewer was referred.20
– The dimension value identifies the video from which the viewer was referred.25
– The dimension value identifies the product ID, which is a Google Knowledge Graph ID.26
– The dimension value identifies the hashtag that led to the referred traffic.27
– The dimension value identifies the video from which the viewer was referred.28
– The dimension value specifies the channel ID from which the viewer was referred via Live Redirects.30
– The dimension value specifies the video from which the viewer was referred.
Devices
- device_type
- This dimension identifies the physical form factor of the device on which the view occurred.
The following table lists valid dimension values:
Values 100
Unknown 101
Computer 102
TV 103
Game console 104
Mobile phone 105
Tablet - operating_system
- This dimension identifies the software system of the device on which the view occurred.
The following table lists valid dimension values:
Values 1
Other 2
Windows 3
Windows Mobile 4
Android 5
iOS 6
Symbian 7
Blackberry 9
Macintosh 10
PlayStation 11
Bada 12
WebOS 13
Linux 14
Hiptop 15
MeeGo 16
Wii 17
Xbox 18
PlayStation Vita 19
Smart TV 20
Nintendo 3DS 21
Chromecast 22
Tizen 23
Firefox 24
RealMedia 25
KaiOS 26
Roku 27
Nintendo Switch 28
Apple tvOS 29
Fire OS 30
ChromeOS 31
Vidaa
Demographics
Demographic dimensions help you to understand the age range and gender distribution of your audience. The YouTube Help Center contains additional information about demographic data in YouTube Analytics reports.
- age_group (core dimension)
- This dimension identifies the age group of the logged-in users associated with the report data. The API uses the following age groups:
AGE_13_17
AGE_18_24
AGE_25_34
AGE_35_44
AGE_45_54
AGE_55_64
AGE_65_
- gender (core dimension)
- This dimension identifies the gender of the logged-in users associated with the report data.
Valid values are
FEMALE
,MALE
andGENDER_OTHER
. This is a core dimension and is subject to the Deprecation Policy.
Engagement and content sharing
- This dimension identifies the service that was used to share videos. Videos can be shared on YouTube (or via the YouTube player) using the "Share" button. This is a core dimension and is subject to the Deprecation Policy.
The following table lists valid dimension values:
Values 0
Unknown 1
Digg 4
reddit 5
StumbleUpon 6
mixi 7
Yahoo! Japan 8
goo 9
Ameba 10
Facebook 11
Myspace 12
NUjij 18
Tuenti 20
menéame 21
Wykop 22
Skyrock 25
Fotka 28
hi5 31
Twitter 32
Cyworld 34
Blogger 36
VKontakte (ВКонтакте) 37
Rakuten (楽天市場) 38
LiveJournal 39
Odnoklassniki (Одноклассники) 40
tumblr. 42
Linkedin 43
Google+ 44
Weibo 45
Pinterest 46
Email 47
Facebook Messenger 49
WhatsApp 50
Hangouts 51
Gmail 52
Kakao (Kakao Talk) 53
Other 55
Copy to Clipboard 59
Embed 60
Text message 61
Android messaging 62
Verizon messages 63
HTC text message 64
Sony Conversations 65
Go SMS 66
LGE Email 67
Line 68
Viber 69
Kik 70
Skype 71
Blackberry Messenger 72
WeChat 73
KAKAO Story 74
Dropbox 75
Telegram 76
Facebook Pages 77
GroupMe 78
Android Email 79
Motorola Messaging 80
Nearby Share 81
Naver 82
iOS System Activity Dialog 83
Google Inbox 84
Android Messenger 85
YouTube Music 86
YouTube Gaming 87
YouTube Kids 88
YouTube TV
See the help docs for more information.
Annotations
- annotation_type
- This dimension identifies the manner in which the annotation displays during the video. The following table lists possible dimension values:
Values 0
Unknown 1
Note 3
Spotlight 4
Title 8
Speech bubble 9
Label 10
Branding watermark 11
Featured video 12
Featured playlist 30
Call-to-Action - annotation_id
- The ID that YouTube uses to uniquely identify an annotation.
Cards
- card_type
- This dimension identifies the type of card that was displayed to the user. The following table lists possible dimension values:
Values 0
Unknown 60
Link 61
Fundraising 62
Video 63
Playlist 65
Fan Funding 66
Merchandise 68
Associated website 69
Channel - card_id
- The ID that YouTube uses to uniquely identify a card.
End screens
- end_screen_element_type
- This dimension identifies the type of end screen element that was displayed to the user. The following table lists the end screen element types and their values:
Values 501
Video - The element promotes another YouTube video. 502
Playlist - The element promotes YouTube playlist. 503
Website - The element links to your associated website. 504
Channel - The element links to another channel. 505
Subscribe - The element encourages subscriptions to your channel. 506
Associated 507
Crowdfunding - The element links to an approved crowdfunding website. 508
Merchandise - The element links to an approved merchandise website. 509
Recent upload - The element links to your channel's most recently uploaded video. 510
Best for viewer - end_screen_element_id
- The ID that YouTube uses to uniquely identify an end screen element.
Subtitles
- subtitle_language
- This dimension identifies the closed caption language used for the longest time during the view. Views for which closed captions were mostly turned off are not counted. See the documentation for channel reports or content owner reports for more information about reports that contain this dimension.
- subtitle_language_autotranslated
- This dimension identifies the auto-translated closed caption language used for the longest time during the view. Views for which closed captions were mostly turned off are not counted. See the documentation for channel reports or content owner reports for more information about reports that contain this dimension.
Ad performance
- ad_type
- The
ad_type
dimension is used in ad performance reports and aggregates the requested metrics based on the types of ads that ran during video playbacks. The following table lists possible dimension values. See the YouTube Help Center for more information about YouTube advertising formats.
Value Description Value in Query Reports 1
Skippable video ads (Auction) auctionTrueviewInstream
2
Display ads (Auction) auctionDisplay
3
Non-skippable video ads (Auction) auctionInstream
5
Display ads (Reserved) reservedDisplay
6
Non-skippable video ads (Reserved) reservedInstream
13
Unknown unknown
15
Skippable video ads (Reserved) reservedInstreamSelect
19
Bumper ads (auction) auctionBumperInstream
20
Bumper ads (reserved) reservedBumperInstream
Note: Query reports might return for some additional ad types that were previously used on YouTube.
Content owner dimensions
The following dimensions are only used in content owner reports.
- claimed_status (only used in content owner reports)
- This dimension indicate that a row of data only contains metrics for claimed content. The only valid value for this dimension is
claimed
. The table in the definition of theuploader_type
dimension provides more detail about how to use this dimension.
- uploader_type (core dimension) (only used in content owner reports)
- This dimension indicates whether a row of data contains metrics for content uploaded by the specified content owner and/or content uploaded by third parties, such as user-uploaded videos. Valid values are
self
andthirdParty
. This is a core dimension and is subject to the Deprecation Policy.
The table below shows the supported combinations for theclaimed_status
anduploader_type
dimensions:
claimed_status
valueuploader_type
valueDescription [Not set] self The row contains YouTube Analytics data for claimed and unclaimed content uploaded by the content owner. claimed self The row contains data for claimed content uploaded by the content owner. claimed thirdParty The row contains data for claimed content uploaded by a third party.