The YouTube Analytics API and the YouTube Reporting API both enable developers to retrieve YouTube Analytics data, albeit in different ways. This document provides a brief overview of the two APIs with the goal of helping you to choose the right API for your application.
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.
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. - 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. |
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. |
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 asychronously 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 7-day periods, 30-day periods, or months. | 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) 7DayTotals 30DayTotals 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.