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.

    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'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:
    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 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:
    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 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:
    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 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:
    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 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 traffic_source_detail dimension identifies the page URL. In query reports, this traffic source type is identified as YT_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 is 9 , then the traffic_source_detail dimension identifies the external web page. In query reports, this traffic source type is identified as EXT_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 as ANNOTATION .
    14
    Playlists
    Views occurred while the video was being played as part of a playlist. In query reports, this traffic source type is identified as PLAYLIST .

    Note that this traffic source differs from source type 18 , 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 as NOTIFICATION . 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 as YT_PLAYLIST_PAGE .

    Note that this traffic source differs from source type 14 , 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 as CAMPAIGN_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 as END_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 .
    29
    Podcasts
    Views originated from the YouTube Podcasts page.
    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_
    This is a core dimension and is subject to the Deprecation Policy .
    gender (core dimension)
    This dimension identifies the gender of the logged-in users associated with the report data. Valid values are FEMALE , MALE and GENDER_OTHER . This is a core dimension and is subject to the Deprecation Policy .
    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
    The YouTube Help Center provides more detail about the different types of annotations as well as the process of adding annotations to your videos.
    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
    The YouTube Help Center provides more detail about the different types of cards as well as the process of adding cards to your videos.
    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 the uploader_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 and thirdParty . This is a core dimension and is subject to the Deprecation Policy .

    The table below shows the supported combinations for the claimed_status and uploader_type dimensions:

    claimed_status value uploader_type value Description
    [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.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: