YouTube Analytics API - Data Model

The YouTube Analytics API enables you to generate custom reports containing YouTube Analytics data. The API supports reports for channels and for content owners. Report fields are characterized as either dimensions or metrics:

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

In a report, each row of data has a unique combination of dimension values. As such, the dimensions you choose for a report determine how YouTube calculates the values for the metrics in that report.
Metrics are individual measurements related to user activity, ad performance, or estimated revenue. User activity metrics include things like video view counts and ratings (likes and dislikes).

The Analytics API provides filtering and sorting parameters, so the calling application does not need to natively support those functions. The API also allows you to retrieve data for YouTube Analytics groups, where a group is a custom collection of up to 500 videos, playlists, channels, or assets.

Choosing report parameters

When you request a report, using the API's reports.query method, the API request contains five parameters that determine how the report values will be calculated:

The startDate and endDate parameters specify the time period for which the report will contain data. The API response actually contains data up until the last day specified for which all metrics in the query are available at the time of the query.
The metrics parameter specifies the measurements that will be included in the report. In channel reports, metrics measure user activity and include values like views and likes. Some metrics also measure ad performance or estimated revenue.
The dimensions parameter explains how the metrics will be grouped.
The filters parameter explains how the report data will be filtered. So, for example, instead of returning all of the data for a channel, a report could be filtered to only contain metrics for a certain country, video, or group of videos.

Note: The API lets you specify multiple values for the video, playlist, and channel filters. If you do so, then you can also include that filter in the list of dimensions so that the returned metrics are also grouped by video, playlist, or channel.

Sample reporting options

As an example, suppose a channel owner wants to retrieve a video device type report to determine how many views of the channel's videos occurred on mobile devices, game consoles, TVs, and so forth.

The channel owner sets the startDate parameter to 2015-06-01 and the endDate parameter to 2015-07-31. Based on these values, the report will contain data for a two-month period.
The device type report supports the views and estimatedMinutesWatched metrics, so the channel owner sets the metrics parameter to views,estimatedMinutesWatched.
For the dimensions parameter, the channel owner has a number of options. Two of them are shown in the following list, and a third is discussed in the explanation of the filters parameter value later in this section.
- Setting the parameter value to deviceType means that the view counts and watch time counts will be grouped by device type for the entire period that the report covers. So, with this value, the report data will answer questions like:
  - How many times were the channel's videos viewed on mobile devices between June 1, 2015, and July 31, 2015?
  - How many times were the channel's videos viewed on game consoles between June 1, 2015, and July 31, 2015?
  The report will actually contain a total view and watch time count for each device type.
- Setting the parameter value to day,deviceType means that the view counts and watch time counts will be calculated by device type for each day during the reporting period. So, with this value, the report data will answer questions like:
  - How many times were the channel's videos viewed on mobile devices on June 1, 2015?
  - How many times were the channel's videos viewed on televisions on July 14, 2015?
Finally, the filters parameter allows the channel owner to restrict the report to include only data matching particular filter values. The report supports too many filtering options to explain all of them, so these examples represent only a fraction of the reports you could generate.
- The channel owner could filter the request to return values only for the Android operating system. (How many views occurred on Android mobile devices during the reporting period?)
- The channel owner could filter the request to return values only for a particular country. (How many times were videos viewed in Canada on each day of the reporting period?)
- The channel owner could filter the request to return values only for particular videos. However, the video filter supports a comma-separated list of values, so the report could actually contain data for many videos.
  
  In addition, if the video filter specifies multiple values, then video can also be specified as a dimension. That means that the dimensions parameter also supports the values deviceType,video and day,deviceType,video.
  - If the channel owner includes video in the list of dimensions, then the metrics specify individual values for each video. (How many times was video XYZ viewed on a game console on June 1, 2015?)
  - If the channel owner does not include video in the list of dimensions, then the metrics specify total values covering all of the specified videos. (How many times were videos ABC, DEF, and XYZ viewed on a game console on June 1, 2015?)

Retrieving reports

To retrieve a report, send an authorized GET request to the API's reports.query method, specifying the parameters that define the report that you want to retrieve.

See the channel reports and content owner reports documentation for a list of reports that the API supports. Each report definition identifies the values that the report allows for the metrics, dimensions, and filters parameters.

Best practices

Applications that use the YouTube Analytics API should always follow these practices:

Use a response's header row to determine the ordering of the report's columns. For example, do not assume that views will be the first metric returned in a response just because it is the first metric listed in a report description. Instead, use the response's header row to determine which column contains that data.
Use the YouTube Data API to retrieve additional metadata for resources identified in YouTube Analytics API responses. As noted in the YouTube API Services Developer Policies (sections III.E.4.b through III.E.4.d), API clients must either delete or refresh stored resource metadata from that API after 30 days.

Aggregate metrics and deleted items

YouTube Analytics API responses do not contain metric breakdowns for deleted items. For example, if a channel owner deletes a video, then that video would no longer be listed in an API response that returns metrics on a video-by-video basis. However, reports that aggregate metrics for a set of resources do still include metrics associated with deleted items.

For example, suppose a channel owner retrieves two reports. The first report lists total daily views for all of the channel's videos over a particular time period. The second report lists total daily views on a video-by-video basis over the same time period.

In this case, the numbers in the first report will include views of videos that were later deleted because the first report contains daily aggregates. However, the second report will not include views associated with deleted items because the second report lists views on a video-by-video basis. As a result, if the channel deleted videos during the time period that the report covers, then the total daily viewcounts reported in the first report might be higher than the sum of the daily, video-specific viewcounts in the second report.

Data anonymization

Some YouTube Analytics data is limited when metrics do not meet a certain threshold. This can happen in a variety of reports. In practice, it means that a report might not contain all (or any) of your data if:

a video or channel has limited traffic during a specified time period,

or
you have selected a filter or dimension, such as traffic source or country, for which values do not meet a certain threshold.

In cases when data is limited, there may be a difference between the totals reported in different reports depending on how those reports aggregate data.

For example, suppose a channel owner retrieves two reports. The first report lists total views for a particular video, and the second report lists total views for that video on a country-by-country basis. During the specified time period, assume that the video was viewed 1000 times, where 500 views occurred in the United States, 498 occurred in Canada, and two occurred in France.

In this example, the first report would indicate that the video was viewed 1000 times. The second report would indicate only that the video was viewed 500 times in the United States and 498 times in Canada. As such, there would be a difference between the total view counts in the two reports. Note that the second report would not contain any indication that two other views had also occurred (or that any views had occurred in France).

The actual thresholds at which data is limited are not published and subject to change at YouTube's discretion.

Limited data types

The following data might be limited in YouTube Analytics reports:

Demographics data, such as age and gender.
Geographic data, including metrics or dimensions related to the countries or regions where the viewers were located, such as their countries or regions. Note, however, that reports do not apply geography thresholds to revenue metrics.
Metrics related to specific traffic sources, such as search terms or external URLs that led to views of your videos. For instance, search terms and URLs that lead very small numbers of views will not appear in reports, though you will still see terms and URLs that drive a lot of viewers to your content.

See the YouTube Help Center for more information about limited data in YouTube Analytics reports.

Quota usage

Each API request that you make counts as one unit of your API usage quota. Quota limits are visible on the Quotas panel in the Google API Console.