The YouTube Analytics API lets you 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 lets you 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`](https://developers.google.com/youtube/analytics/v1/reference/reports/query) method, the API request contains five parameters that determine how the report values will be calculated: - The [`startDate`](https://developers.google.com/youtube/analytics/v1/reference/reports/query#startDate) and [`endDate`](https://developers.google.com/youtube/analytics/v1/reference/reports/query#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`](https://developers.google.com/youtube/analytics/v1/reference/reports/query#metrics) parameter specifies the measurements that will be included in the report. In channel reports, metrics measure user activity and include values like [views](https://developers.google.com/youtube/analytics/v1/dimsmets/mets#views) and [likes](https://developers.google.com/youtube/analytics/v1/dimsmets/mets#likes). Some metrics also measure ad performance or estimated revenue. - The [`dimensions`](https://developers.google.com/youtube/analytics/v1/reference/reports/query#dimensions) parameter explains how the metrics will be grouped. - The [`filters`](https://developers.google.com/youtube/analytics/v1/reference/reports/query#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](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#video), [playlist](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#playlist), and [channel](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#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](https://developers.google.com/youtube/analytics/v1/dimsmets/mets#views) and [estimatedMinutesWatched](https://developers.google.com/youtube/analytics/v1/dimsmets/mets#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](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#video) filter supports a comma-separated list of values, so the report could actually contain data for many videos. In addition, if the [video](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#video) filter specifies multiple values, then [video](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#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](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#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](https://developers.google.com/youtube/analytics/v1/dimsmets/dims#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?) ## Data freshness and latency While the YouTube Analytics API supports targeted queries, the underlying analytics data is not real-time. Data processing typically introduces a latency of 48 to 72 hours. Therefore, API responses do not contain data for the most recent days, and the `endDate` of your report only includes data up until the last day for which all requested metrics are fully processed. Given the data latency, you might notice discrepancies between the data returned by the API and the real-time metrics visible in YouTube Studio. If your application requires real-time statistics for individual videos, such as current view, like, or comment counts, use the [YouTube Data API's `videos.list` method](https://developers.google.com/youtube/data/reference/rest/v3/videos/list) instead of the YouTube Analytics API. ## Retrieving reports To retrieve a report, send an authorized GET request to the API's [`reports.query`](https://developers.google.com/youtube/analytics/v1/reference/reports/query) method, specifying the parameters that define the report that you want to retrieve. See the [channel reports](https://developers.google.com/youtube/analytics/v1/channel_reports) and [content owner reports](https://developers.google.com/youtube/analytics/v1/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](https://developers.google.com/youtube/analytics/v1/dimsmets/mets#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](https://developers.google.com/youtube/data/reference/rest) to retrieve additional metadata for resources identified in YouTube Analytics API responses. As noted in the [YouTube API Services Developer Policies](https://developers.google.com/youtube/terms/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: 1. a video or channel has limited traffic during a specified time period, or 2. 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). > [!NOTE] > **Note:** 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 example, 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](https://support.google.com/youtube/answer/9101241) 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](https://console.developers.google.com/iam-admin/quotas?service=youtubeanalytics.googleapis.com) panel in the Google Cloud console.