YouTube

Dimensions

This document defines the different dimensions that the API supports for aggregating and filtering YouTube Analytics data. The dimensions are grouped in the following categories. For each category, the document links to a list of sample requests that use dimensions in that category.

  1. Reporting entity dimensionsvideo, channel*, and show*
  2. Geographic dimensionscountry, province, continent, subContinent
  3. Temporal dimensionsday, 7DayTotals, 30DayTotals, and month
  4. Playback location dimensionsinsightPlaybackLocationType
  5. Traffic source dimensionsinsightTrafficSourceType
  6. Device dimensionsdeviceType, operatingSystem
  7. Demographic dimensionsageGroup and gender
  8. Social dimensionssharingService
  9. Content owner dimensionsclaimedStatus*, uploaderType*, and adType

* Dimensions marked with an asterisk in the list above are only supported for content owner reports and ad performance reports.

Dimensions marked with a dagger in the list above are only supported for ad performance reports.

Dimensions marked with a double dagger in the list above can only be used as filters. To use these dimensions, set the filters query parameter to the appropriate value.

Note: The channel dimension is supported for content owner reports since those reports typically aggregate data for multiple channels. Channel reports also include data for a specific channel, but the channel is identified using the ids parameter.

Core dimensions

While the YouTube Analytics 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 also identifies the API's core dimensions:

See the list of YouTube APIs subject to the Deprecation Policy for more information.

Reporting entity dimensions

video (core dimension)
The ID of a YouTube video. If you are using the YouTube Data API (v3), this is the value of the id property in a video resource. This is a core dimension and is subject to the Deprecation Policy.

channel (core dimension)
The ID for a YouTube channel. If you are using the YouTube Data API (v3), this is the value of the id property in a channel resource. This is a core dimension and is subject to the Deprecation Policy.
show
The ID for a YouTube show. If you are using the YouTube Data API 2.0, you can retrieve additional show data from the Movies and Shows feed.
Important: API requests to retrieve content owner reports must filter data using either one of these dimensions (video, channel, or show) or a supported combination of the claimedStatus and uploaderType dimensions.

Examples

The following sample requests use reporting entity dimensions or filters:

  • Channel examples

    • Basic stats
      • Top 10 – Most watched videos for a channel
      • Top 10 – Annotation click-through rates for a channel's most viewed videos
    • Geographic
      • Top 10 – Most viewed videos in a specific country
      • Top 10 – Most viewed videos in Europe

  • Content owner examples

    • Basic stats
      • Top 10 - Most viewed videos for a content owner
      • Top 10 - Most watched videos for a content owner
      • Top 10 - Most viewed videos for a content owner's channel
      • Top 10 – Annotation click-through rates for a channel's most viewed videos
    • Geographic
      • Top 10 - Most watched videos in Europe for a content owner

Geographic dimensions

country (core dimension)
A two-letter ISO-3166-1 country code, such as US, CN (China), or FR (France). This is a core dimension and is subject to the Deprecation Policy.

province
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). When an API request includes province in the dimensions parameter value, the request must also restrict data to the United States by including country==US in the filters parameter value.

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.

continent (filter only)
A United Nations (UN) statistical region code. The API supports the following values:
  • 002: Africa
  • 019: Americas (Northern America, Latin America, South America, and the Caribbean)
  • 142: Asia
  • 150: Europe
  • 009: Oceania
This dimension can only be used to filter data. To use this dimension, set the value of the filters parameter to continent==REGION_CODE, specifying a REGION_CODE value from the list above.

subContinent (filter only)
A UN statistical region code that identifies a geographical sub-region. The United Nations Statistics Division lists sub-regions as well as the countries it associates with each region.

This dimension can only be used to filter data. To use this dimension, set the value of the filters parameter to subContinent==REGION_CODE, specifying a REGION_CODE value from the UN list.

Examples

The following sample requests use geographic dimensions or filters:

  • Channel examples

    • Basic stats: Country-specific viewcounts (and more) for a channel
    • Geographic
      • Country-specific watch time metrics for a channel's videos
      • Country-specific annotation metrics for a channel's videos
      • Province-specific metrics for U.S. states and Washington D.C.
    • Playback location: Daily viewcounts and watch time from different playback locations
    • Traffic source: Viewcounts and watch time from different traffic sources in a country
    • Demographic: Viewer demographics in California (age group and gender)
    • Top videos
      • Top 10 – Most viewed videos in a specific country
      • Top 10 – Most viewed videos in Europe

  • Content owner examples

    • Basic stats: Country-specific viewcounts (and more) for all self-uploaded videos
    • Geographic
      • Country-specific watch time metrics for self-uploaded content
      • Country-specific annotation metrics for self-uploaded content
      • Province-specific metrics for U.S. states and Washington D.C.
    • Playback location: Daily viewcounts and watch time from different playback locations
    • Demographic: Viewer demographics in California (age group and gender)
    • Top videos: Top 10 – Most watched videos in Europe for a content owner
    • Earnings/Ad performance: Country-specific earnings and ad performance metrics

Temporal dimensions

These dimensions indicate that an Analytics report should aggregate data based on a time period, such as a day, a week, or a month. The start-date and end-date request parameters specify the time period for which the report will include data. In reports, dates will be listed in YYYY-MM-DD format.

day (core dimension)
Data in the report will be aggregated on a daily basis so that each row will contain data for one day. You can use other filters to break down the data even further. For example, a channel report could list daily views for a particular video or total views in a particular country for all of the channel's videos. This is a core dimension and is subject to the Deprecation Policy.br/>
7DayTotals (core dimension)
Data in the report will be aggregated so that each row contains data for a seven-day period. In the report, the 7DayTotals column will specify the end date of a seven-day period. So, a row containing a day value of 2012-06-07 would contain data for the period starting June 1, 2012, and ending June 7, 2012. As with daily reports, you can use other filters to segment the data even further.

Note: The uniques metric in the report specifies the number of unique cookies associated with views in the seven-day period. (This number will overcount users who are using multiple devices or browsers.) This is a core dimension and is subject to the Deprecation Policy.br/>
30DayTotals (core dimension)
Data in the report will be aggregated so that each row contains data for a 30-day period. In the report, the 30DayTotals column or property will specify the end date of a 30-day period. So, a row containing a day value of 2012-01-31 would contain data for the period starting January 2, 2012, and ending January 31, 2012. As with daily reports, you can use other filters to segment the data even further.

Note: The uniques metric in the report specifies the number of unique cookies associated with views in the 30-day period. (This number will overcount users who are using multiple devices or browsers.) This is a core dimension and is subject to the Deprecation Policy.br/>
month (core dimension)
Data in the report will be aggregated by calendar month. As with daily reports, you can use other filters to segment the data even further. In the report, dates will be listed in YYYY-MM format.

Note: If your API query uses the month dimension, then the start-date and end-date parameters must both be set to the first day of the month. This is a core dimension and is subject to the Deprecation Policy.

Examples

The following sample requests use temporal dimensions or filters:

  • Channel examples

    • Time-based
      • Daily watch time metrics for a channel's videos
      • Daily annotation metrics for a channel's videos
    • Playback location: Daily viewcounts and watch time from different playback locations
    • Traffic source: Daily viewcounts and watch time from different traffic sources
    • Device/OS
      • Daily device type metrics for the Android operating system
      • Daily operating system metrics for mobile devices
      • Daily operating system and device type metrics

  • Content owner examples

    • Time-based
      • Daily watch time metrics for self-uploaded content
      • Annotation metrics for claimed content
    • Playback location: Daily viewcounts and watch time from different playback locations
    • Traffic source: Daily viewcounts and watch time from different traffic sources
    • Device/OS
      • Daily device type metrics for claimed videos
      • Daily operating system metrics for claimed videos viewed on mobile devices
      • Daily operating system and device type metrics
    • Earnings/Ad performance: Daily earnings and ad performance metrics

Playback location dimensions

insightPlaybackLocationType
Data in the report will be aggregated based on the type of page or application where video playbacks occurred. Possible values for this dimension are:

  • CHANNEL – The data describes views that occurred on a channel page.

  • WATCH – The data describes views that occurred on the video's YouTube watch page or in an official YouTube application, such as the YouTube Android app.

  • EMBEDDED – The data describes views that occurred on another website or application where the video was embedded using an <iframe> or <object> embed.

  • EXTERNAL_APP – The data describes views that occurred in a third-party application where the video was played using a method other than an <iframe> or <object> embed. For example, playbacks in applications that use the YouTube Android Player API would be categorized using this value.

  • MOBILE – The data describes views that occurred on YouTube's mobile website or on approved YouTube API clients, including mobile devices.

    As of September 10, 2013, playbacks are no longer categorized as MOBILE playbacks in YouTube Analytics reports. The value may remain in reports since legacy data will still fall under that category. However, following that date, mobile playbacks are classified as either WATCH, EMBEDDED, or EXTERNAL_APP playbacks, depending on the type of application where the playbacks occur.

  • YT_OTHER – The data describes views that are not otherwise classified.

insightPlaybackLocationDetail
Data will be aggregated based on the page where the player is located. Note that this report is only supported for views that occurred in embedded players, and it identifies the embedded players that generated the most views for a specified video. Thus, it provides a more fine-grained view than the playback location report by identifying the URLs or applications associated with the top embedded players.

Examples

The following sample requests use playback location dimensions:

  • Channel examples

    • Playback location
      • Viewcounts and watch time from different playback locations
      • Daily viewcounts and watch time from different playback locations
      • Top 10 – Third-party sites that generate the most views for an embedded video

  • Content owner examples

    • Playback location
      • Viewcounts and watch time from different playback locations
      • Daily viewcounts and watch time from different playback locations
      • Top 10 – Third-party sites that generate the most views for an embedded video

Traffic source dimensions

insightTrafficSourceType
Data in the report will be aggregated based on the referrer type, which describes the manner in which users reached the video. Possible values for this dimension are:
  • ADVERTISING – The viewer was referred to the video by an advertisement. If you filter based on this traffic source, the insightTrafficSourceDetail field will identify the type of advertisement.
  • ANNOTATION – Viewers reached the video by clicking on an annotation in another video.
  • EXT_URL – The video views were referred from a link on a web page. If you filter based on this traffic source, the insightTrafficSourceDetail field will identify the web page.
  • GOOGLE_SEARCH – The video views were referred from Google search results. If you filter based on this traffic source, the insightTrafficSourceDetail field will specify the search term.
  • NO_LINK_EMBEDDED – The video was embedded on another website when it was viewed.
  • NO_LINK_OTHER – YouTube did not identify a referrer for the traffic. This category encompasses direct traffic to a video as well as traffic on mobile apps.
  • PLAYLIST – The video views were referred from a playlist.
  • PROMOTED – The video views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
  • RELATED_VIDEO – The video views were referred from a related video listing on another video watch page. If you filter based on this traffic source, the insightTrafficSourceDetail field will specify the video ID for that video.
  • SUBSCRIBER – The video views were referred from feeds on the YouTube homepage or from YouTube subscription features. If you filter based on this traffic source, the insightTrafficSourceDetail field will specify the homepage feed items or other page from which views were referred.
  • YT_CHANNEL – The video views occurred on a channel page. If you filter based on this traffic source, the insightTrafficSourceDetail field will specify the channel ID for that channel.
  • YT_OTHER_PAGE – The video views were referred from a link other than a search result or related video link that appeared on a YouTube page. If you filter based on this traffic source, the insightTrafficSourceDetail field will identify the page.
  • YT_SEARCH – The video views were referred from YouTube search results. If you filter based on this traffic source, the insightTrafficSourceDetail field will specify the search term.
insightTrafficSourceDetail
Data in the report will be aggregated based on the referrers that generated the most views for a specified video and a specified traffic source type. The list below identifies the traffic sources for which this report is available. For each traffic source, the list identifies the information that the insightTrafficSourceDetail dimension provides.
  • ADVERTISING – The type of advertisement that led to the views.
  • EXT_URL – The website that referred the viewers to the video.
  • GOOGLE_SEARCH – The search term that led viewers to the video.
  • RELATED_VIDEO – The related video that led viewers to the video covered in the report.
  • SUBSCRIBER – The related video that led viewers to the video covered in the report. Valid values are:
    • activity – Views from items in homepage subscription feeds that resulted from non-upload and non-social channel activity, including likes, favorites, bulletin posts, and playlist additions.
    • blogged – Views from items in homepage subscription feeds that resulted from links from top blogs.
    • mychannel – Views from items in other feeds listed on the homepage, such as "Likes," "Watch History," and "Watch Later."
    • sdig – Views originating from subscription update emails.
    • uploaded – Views from the uploaded items in homepage subscription feeds.
    • / – Other views originating from the YouTube homepage.
    • /my_subscriptions – Views originating from users' My subscriptions pages on YouTube.
  • YT_CHANNEL – The channel page where viewers watched the video.
  • YT_OTHER_PAGE – The YouTube page from which viewers were referred to the video.
  • YT_SEARCH – The search term that led viewers to the video.

Examples

The following sample requests use traffic source dimensions:

  • Channel examples

    • Traffic source
      • Viewcounts and watch time from different traffic sources in a country
      • Daily viewcounts and watch time from different traffic sources
      • Top 10 – YouTube search terms that generate the most traffic for a video
      • Top 10 – Google search terms that generate the most traffic for a video

  • Content owner examples

    • Traffic source
      • Viewcounts and watch time from different traffic sources
      • Daily viewcounts and watch time from different traffic sources
      • Top 10 – YouTube search terms that generate the most traffic for a video
      • Top 10 – Google search terms that generate the most traffic for a video

Device dimensions

deviceType
The physical form factor of the device on which the view occurred. The list below identifies the device types for which the API returns data. You can also use the deviceType dimension as a filter to restrict an operating system report to only contain data for a specific type of device.
  • DESKTOP
  • GAME_CONSOLE
  • MOBILE
  • TABLET
  • TV
  • UNKNOWN_PLATFORM
operatingSystem
The software system of the device on which the view occurred. The list below identifies the operating systems for which the API returns data. You can also use the operatingSystem as a filter to restrict a device type report to only contain data for a specific operating system.
  • ANDROID
  • BADA
  • BLACKBERRY
  • DOCOMO
  • HIPTOP
  • IOS
  • LINUX
  • MACINTOSH
  • MEEGO
  • NINTENDO_3DS
  • OTHER
  • PLAYSTATION
  • PLAYSTATION_VITA
  • SMART_TV
  • SYMBIAN
  • WEBOS
  • WII
  • WINDOWS
  • WINDOWS_MOBILE
  • XBOX

Examples

The following sample requests use device dimensions:

  • Channel examples

    • Device/OS
      • Daily device type metrics for the Android operating system
      • Daily operating system metrics for mobile devices
      • Daily operating system and device type metrics

  • Content owner examples

    • Device/OS
      • Daily device type metrics for claimed videos
      • Daily operating system metrics for claimed videos viewed on mobile devices
      • Daily operating system and device type metrics

Demographic dimensions

The YouTube Help Center contains additional information about demographic data in YouTube Analytics reports.

ageGroup (core dimension)
The age group of the logged-in users associated with the report data. The API uses the following age groups:
  • 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 (core dimension)
The gender of the logged-in users associated with the report data. Valid values are female and male. This is a core dimension and is subject to the Deprecation Policy.

Examples

The following sample requests use demographic dimensions:

  • Channel examples

    • Demographic: Viewer demographics in California (age group and gender)

  • Content owner examples

    • Demographic: Viewer demographics in California (age group and gender)

Social dimensions

sharingService (core dimension)
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.

See the help docs for more information.

Examples

The following sample requests use social dimensions:

  • Channel examples

    • Social: Sharing metrics, aggregated by service where videos were shared

  • Content owner examples

    • Social: Sharing metrics, aggregated by service where videos were shared

Content owner dimensions

The following dimensions are only supported for content owner reports.

Important: API requests to retrieve content owner reports must filter data using one of the following dimensions:
  • video
  • channel
  • show
  • A supported combination of the claimedStatus and uploaderType dimensions as defined below.
claimedStatus
This dimension lets you indicate that an API response should only contain metrics for claimed content. The only valid value for this dimension is claimed. If the filters parameter restricts the query to claimedStatus==claimed, the API will only retrieve data for claimed content. The table in the definition of the uploaderType dimension provides more detail about how to use this dimension.
uploaderType (core dimension)
This dimension lets you indicate whether an API response should contain 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 claimedStatus and uploaderType dimensions, which are both used in the filters parameter:

claimedStatus value uploaderType value Description
[Not set] self Retrieves YouTube Analytics data for claimed and unclaimed content uploaded by the content owner.
claimed [Not set] Retrieves data for claimed content uploaded by the content owner or by a third party.
claimed self Retrieves data for claimed content uploaded by the content owner.
claimed thirdParty Retrieves data for claimed content uploaded by a third party.
adType

The adType dimension is used in ad performance reports and aggregates the requested metrics based on the types of ads that ran during video playbacks. Possible values for these dimensions are:

  • auctionDisplay – A rich media or image ad that appears either as an overlay on the bottom of the video player, as a 300x250 ad unit on the video watch page, or as a combination of both. When the overlay runs, it automatically closes after displaying for a certain amount of time, and the user can close the overlay as well. If an overlay and a banner are shown together, each ad is counted as a separate impression.

  • auctionInstream – Non-skippable video ads that run before, during, or after the main video.

  • auctionTrueviewInslate – The viewer chooses one of several video ads from a selection of choices displayed before a video. See the TrueView documentation for more information.

  • auctionTrueviewInstream – Skippable video ads that run before or during the main video. See the TrueView documentation for more information.

  • auctionUnknown – An ad that was purchased via the AdWords auction but that has not been classified into one of the other ad types.

  • reservedClickToPlay – A video ad that the user must click to initiate playback. An ad impression is recorded any time the click-to-play ad unit displays, regardless of whether the user initiates a playback. These are sold on a reserved basis.

  • reservedDisplay – A rich media or image ad that appears either as an overlay on the bottom of the video player, as a 300x250 ad unit on the video watch page, or as a combination of both. When the overlay runs, it automatically closes after displaying for a certain amount of time, and the user can close the overlay as well. If an overlay and a banner are shown together, each ad is counted as a separate impression.

  • reservedInstream – Non-skippable video ads that are inserted before, during, or after the main video.

  • reservedMasthead – A large ad, which can include video and graphic elements, that appears on the homepage.

  • reservedUnknown – An ad that was sold on a reserved basis that could not be classified into one of the other ad types.

  • unknown – We could not classify this ad type.

Examples

Many of the sample API requests for content owner reports use a supported combination of the claimedStatus and uploaderType dimensions to filter data. In addition, all of the sample earnings and ad performance reports, which are listed below, use dimensions that are only supported for content owner reports.

  • Earnings and ad performance metrics for claimed content
  • Daily earnings and ad performance metrics
  • Country-specific earnings and ad performance metrics
  • Top 10 – Videos with the highest earnings
  • Ad performance metrics for different ad types

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.