Dimensions

This document defines the dimensions that the YouTube Analytics API supports. This API supports real-time, targeted queries to generate custom YouTube Analytics reports.

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 query report identifies the dimensions that it supports. For example, when retrieving user activity by time, you choose the time period for which data will be reported: day or month. In any report, each row of data has a unique combination of dimension values.

To retrieve a query report, call the YouTube Analytics API's reports.query method. In your request, use the dimensions parameter to specify the dimensions that YouTube will use to calculate metric values in the reports.

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 identifies the API's core dimensions.

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

Filters

All query reports support filters. Filters identify dimension values that must be present in the retrieved dataset. As such, they limit an API response to only include data matching a particular value or set of values. For example, instead of retrieving user activity metrics for all countries, you could use a filter to only retrieve data for a particular country.

In a request to retrieve a query report, the optional filters request parameter specifies the dimension values for which you want to filter data. For example, to retrieve user activity metrics for Europe, you would set the filters parameter value to continent==150.

Important: API requests to retrieve content owner reports must filter data by either using one of the reporting entity dimensions or using a supported combination of the claimedStatus and uploaderType dimensions.

Dimensions

The following sections define the dimensions that are used in the YouTube Analytics API's query reports. Unless otherwise noted, these dimensions are used in both channel and content owner reports. Dimensions that can only be used as filters are also identified.

Resources

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

Note: The API lets you specify multiple values for the video, playlist, and channel dimensions when they are used as filters. To do so, set the filters parameter value to a comma-separated list of the video, playlist, or channel IDs for which the API response should be filtered. The parameter value can specify up to 500 IDs.

video (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
The ID of a YouTube playlist. In the YouTube Data API, this is the value of a playlist resource's id property.
channel (core dimension) (only used in content owner reports)
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.

The channel dimension is frequently used in content owner reports because those reports typically aggregate data for multiple channels.
group (filter only)
The ID of a YouTube Analytics group. You can retrieve this value using the YouTube Analytics API's groups.list method. When you use the group filter, the API response contains data for all of the videos, playlists, or channels in that group.

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
      • Statistics for a specific playlist
      • Top 10 – Most watched playlists for a channel
    • 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
      • Top 10 – Most watched playlists for a content owner
    • Geographic
      • Top 10 - Most watched videos in Europe for a content owner
      • Top 10 – Most started playlists in the United States

Geographic areas

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

country (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
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. 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.

dma
The 3-digit identifier that Nielsen uses to identify the Designated Market Area (DMA) associated with the viewing events described in the data row.
city
The estimated city associated with the metrics in the report row. Data for this dimension is available for dates beginning January 1, 2022.
continent (filter only)
A United Nations (UN) statistical region code. The API supports the following values:
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 table.
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 view counts (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.
      • Country-specific watch time metrics for a channel's playlists
      • Top 10 – Most started playlists in the United States
    • Playback location: Daily view counts 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 view counts (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.
      • Country-specific watch time metrics for a content owner's playlists
      • Top 10 – Most started playlists in the United States
    • Playback location: Daily view counts 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
    • Revenue/Ad performance: Country-specific revenue and ad performance metrics

Time periods

These dimensions indicate that a report should aggregate data based on a time period, such as a day, a week, or a month. The startDate and endDate request parameters specify the time period for which the report includes data. Note that the report actually returns data up until the last day for which all metrics specified in the request are available at the time the query is made. In reports, dates are listed in YYYY-MM-DD format.

Important: All dates refer to the time period beginning at 12:00AM Pacific time (UTC-7 or UTC-8) and ending at 11:59PM Pacific time on the specified day, month, and year. As a result, 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.

The month dimension refers to the time period beginning at 12:00AM Pacific time (UTC-7 or UTC-8) on the first day of the specified month and year.

day (core dimension)
When you use this dimension, data in the report is aggregated on a daily basis and each row contains data for one day. You can use other dimensions to break down the data even further. For example, a traffic source report can aggregate daily viewing statistics based on the manner in which users reach your videos. This is a core dimension and is subject to the Deprecation Policy.
month (core dimension)
Data in the report is aggregated by calendar month. As with daily reports, you can use other filters to segment the data even further. In the report, dates are 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
      • Daily playlist views for a channel
    • Playback location: Daily view counts and watch time from different playback locations
    • Traffic source: Daily view counts 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
      • Daily playlist views for a content owner
    • Playback location: Daily view counts and watch time from different playback locations
    • Traffic source: Daily view counts 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
    • Revenue/Ad performance: Daily revenue and ad performance metrics

Playback locations

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

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

  • BROWSE – The data describes views that took place on the YouTube home page or home screen, in the user's subscription feed, or in another YouTube browsing feature.

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

  • EMBEDDED – The data describes views that occurred on another website or application where the video was embedded using an