This document explains similarities and differences in the ways that the YouTube Analytics API and YouTube Reporting API provide access to YouTube Analytics data. The document's purpose is to help you to choose the right API for your application.
Both APIs enable developers to retrieve YouTube Analytics data. In addition, both APIs support YouTube channel owners and YouTube content owners, each of whom can access a specific set of reports:
-
Channel reports contain user activity metrics for a specified channel.
-
Content owner reports aggregate metrics for all of the channels linked to a specified YouTube content owner. For example, a record label could retrieve a report containing combined statistics for the YouTube channels of all of the label's artists. Some content owner reports contain user activity metrics, while others contain metrics related to revenue and ad performance.
The Reporting API also allows some content owners to access system-managed ad revenue reports. The data in the system-managed reports can only be retrieved with the Reporting API.
All YouTube Analytics and YouTube Reporting API requests must be authorized by the channel or content owner that owns the requested data.
Report contents
The reports that the APIs retrieve contain two types of data:
-
Dimensions are common criteria that are used to aggregate data, such as the date on which the user activity 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, each row's combination of dimension values functions as the primary key for that row.
-
Metrics are individual measurements of user activity, ad performance, or estimated revenue. User activity metrics include things like video view counts and ratings (likes and dislikes).
Choose the right API for your application
- YouTube Analytics API
- The YouTube Analytics API supports real-time targeted queries to generate custom YouTube Analytics reports. The API provides filtering and sorting parameters, so the calling application does not need to natively support these functions.
Each API request specifies the date range for which data will be returned. The API also enables you to retrieve weekly and monthly data sets. As such, the calling application does not need to store retrieved data sets or aggregate statistics across date ranges. - YouTube Reporting API
- The YouTube Reporting API retrieves bulk reports containing YouTube Analytics data for a channel or content owner. It is designed for applications that can import large data sets and that provide tools to filter, sort, and mine that data.
Each report contains a predefined set of fields. Developers use the API to schedule reporting jobs, each of which identifies a report that YouTube should generate. YouTube then generates a daily report that can be asynchronously downloaded. Each report contains data for a unique 24-hour period.
In addition, YouTube automatically generates a set of system-managed reports for content owners that have access to the corresponding reports in YouTube Creator Studio. These reports provide programmatic access to ad revenue data. - User activity related to subtitles
- Audience retention data for playlists
- Estimated revenue reports for content owners (2 different reports are available)
- Asset reports for content owners (11 different reports are available)
Supported reports
The following table identifies the different types of reports you can retrieve using the APIs. Targeted queries are available via the YouTube Analytics API, and bulk reports are available via the YouTube Reporting API.
Data that is available in one API might not be available in the other. For example, the YouTube Analytics API lets you retrieve user activity metrics on a weekly or monthly basis, but the YouTube Reporting API requires you to aggregate that data yourself. On the other hand, the YouTube Reporting API supports asset reports for content owners, but that data is not available from the YouTube Analytics API.
| Report types | |
|---|---|
| Video reports | Supported for channels (query or bulk) and content owners (query or bulk). Video reports provide statistics for all user activity related to a channel's videos or a content owner's videos. For example, these reports contain the number of views that your videos received. In the YouTube Analytics API, some content owner video reports also include estimated revenue and ad performance metrics. |
| Playlist reports | Supported for channels (query or bulk) and content owners (query or bulk). Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist. The YouTube Reporting API supports audience retention reports for playlists, but the YouTube Analytics API does not support a similar report. |
| Ad performance reports | Supported for content owners (query or bulk). Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions. |
| Estimated revenue reports | Supported for content owners (bulk). Estimated revenue reports provide the total estimated revenue for videos from Google-sold advertising sources and from non-advertising sources. These reports also contain some ad performance metrics. Note that system-managed reports contain actual revenue. |
| Asset reports | Supported for content owners (bulk). Asset reports provide user activity metrics related to videos that are linked to a content owner's assets. A video is included in a content owner's report if the content owner has claimed that video as a match of one of the content owner's assets. The video could have been uploaded by the content owner or by another YouTube user. |
| System-managed reports | Supported for content owners who have access to the corresponding reports in the Reports section of YouTube's Creator Studio. System-managed reports provide actual revenue data earned by assets and videos. An additional report lists claimed videos and the assets those videos match. Note that not all Creator Studio reports are currently available in the API. Note: YouTube automatically generates system-managed reports for content owners that have access to the corresponding reports in Creator Studio. As a result, the process for retrieving these reports is different than for the other types of reports in this list. See the documentation for system-managed reports for more information. |
Key differences
The following table highlights important differences between the YouTube Analytics and Reporting APIs.
| Feature | YouTube Analytics API | YouTube Reporting API |
|---|---|---|
| Process to retrieve data | Each API request specifies dimensions and metrics to be returned as well as the time period for which data will be returned. | Applications schedule reporting jobs. For each job, YouTube generates daily reports that can be asynchronously downloaded. |
| Date Ranges | Some API reports specify the date that user activity occurred. Some of those reports support dimensions to aggregate user activity metrics by month. | All API reports specify the day that user activity occurred. Applications using the API can implement features to aggregate data for periodic intervals. |
| Filtering data | You can filter reports to include only rows for which a dimension has a specific value. The API also supports some dimensions, like continent and subContinent, that are used only as filters. | The API supports bulk downloads of complete data sets. It does not support filtering or return data for filter-only dimensions. The client application stores the downloaded data and implements its own features to filter the data. |
| Sorting | Reports can be sorted based on returned metric values. Some reports support only a limited number of results. For example, the report that lists a channel's most viewed videos returns a maximum of 200 rows. | This API supports bulk downloads of complete data sets. Client applications can implement their own features to sort downloaded data. |
| Enumerations | API reports contain text values, like "ANDROID" or "CHANNEL," to identify enumerated dimension values. | API reports contain integers that can be mapped to text values. |
| Quota | The API server evaluates each query to determine its quota cost. The quota usage document explains the methodology in more detail. | Quota usage is not an issue because data is retrieved once and then filtered, sorted, and queried within the application. |
| Unique reports |
|
|
| Unique dimensions | group (filter-only dimension) continent (filter-only dimension) subContinent (filter-only dimension) month isCurated==1 (filter-only dimension) viewsPerPlaylistStart averageTimeInPlaylist |
annotation_id annotation_type asset_id card_id card_type live_or_on_demand subscribed_status subtitle_language |
| Unique metrics | uniques relativeRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist |
card_click_rate card_clicks card_impressions card_teaser_click_rate card_teaser_clicks card_teaser_impressions estimated_partner_adsense_revenue estimated_partner_doubleclick_revenue playlist_saves_added playlist_saves_removed |
Naming differences between APIs
The two APIs currently use different naming conventions to identify dimensions and metrics. At this time, YouTube Analytics API names use camelCase, while YouTube Reporting API names use underscore-delimited names.
The following tables identify the different names that the two APIs use to identify the same metrics and dimensions. In some cases, the difference between the two names is more than what you would get after converting a name from camelCase to underscores. For example, the video dimension in the YouTube Analytics API is named video_id in the YouTube Reporting API.