This page lists YouTube Analytics API changes and documentation updates. Subscribe to this changelog.
January 31, 2014
This update contains the following changes:
-
The content owner reports document has been updated to reflect that the
subscribersGained
andsubscribersLost
metrics can now be retrieved for content claimed or uploaded by a content owner.The change is visible in the first basic stats report for content owners, which now supports the
claimedStatus
anduploaderType
filters.
January 16, 2014
This update contains the following changes:
-
The sample requests document has been redesigned to group examples in categories, using a tab format similar to the one recently released for channel and content owner reports. With the new design, examples are grouped into the following categories:
- Basic stats
- Time-based
- Geographic
- Playback location
- Traffic source
- Device/OS
- Demographic
- Social
- Earnings/Ads (for content owner reports only)
-
The sample requests document now includes new examples for retrieving province-specific data in either channel reports or content owner reports.
-
Province-specific metrics for U.S. states and Washington D.C.: This report retrieves a province-by-province breakdown of viewcounts and other statistics for a channel's videos. The data covers U.S. states and Washington D.C. The example uses the
province
dimension, and also uses thefilters
parameter to restrict the response to only include results for the United States. -
Viewer demographics in California (age group and gender): This report retrieves statistics about the age group and gender of viewers in California who watched a channel's videos or, for content owner reports, a content owner's claimed content. This example uses the
filters
parameter to ensure the response only includes data for a particular province.
-
-
The definition of the
province
dimension has been updated to note that whenprovince
is included in thedimensions
parameter value, the request must also restrict data to the United States by includingcountry==US
in thefilters
parameter value.
January 6, 2014
This update contains the following changes:
-
The documents that list the supported channel and content owner reports have been redesigned. Instead of providing a table that lists all possible reports, each document instead groups the reports into categories:
- Basic stats
- Time-based
- Geographic
- Playback location
- Traffic source
- Device/OS
- Demographic
- Social
- Top videos
Each document displays these categories as a list of tabs, and you can click any tab to see the supported reports in that category.
-
The API now supports three new geographic dimensions:
province
,continent
, andsubContinent
.-
The
province
dimension lets you retrieve statistics for U.S. states and for the District of Colombia. The API supports two uses for this dimension:-
The API supports two reports that break statistics down on a state-by-state basis. Both reports are available for channels and content owners.
- The core stats report provides several statistics, including view counts and estimated minutes watched.
- The time-based report provides the same statistics, but aggregates data on a daily, 7-day, 30-day, or monthly basis.
-
You can use the
filters
query parameter to restrict a report to only contain statistics for a particular state. Several reports support this type of filtering, including geographic reports, playback location reports, traffic source reports, device reports, operating system reports, demographic reports, and top-video reports.
-
-
The
continent
dimension specifies a United Nations (UN) statistical region code that identifies a continent. This dimension can only be used as a filter. -
The
subContinent
dimension specifies a United Nations (UN) statistical region code that identifies a sub-region of a continent. This dimension can also only be used as a filter.Since each sub-region is only associated with one continent, there is no need to also use the
continent
filter when you are using thesubContinent
filter. (In fact, the API will return an error if a request uses both dimensions.)
-
-
The documentation has been corrected so that the
insightTrafficSourceDetail
dimension does not include theinsightTrafficSourceType
valuePROMOTED
as a valid filter value.
September 30, 2013
This update contains the following changes:
-
The YouTube Analytics API is now subject to the Deprecation Policy described in the Terms of Service. However, the API's non-core dimensions and non-core metrics are not subject to the Deprecation Policy. The dimensions and metrics pages have been updated to list core dimensions and core metrics. In addition, the definitions on those pages have been updated to explicitly identify core dimensions and metrics.
-
The API now supports
EXTERNAL_APP
as a value for theinsightPlaybackLocationType
dimension. In conjunction with this update, as of September 10, 2013, playbacks are no longer categorized asMOBILE
playbacks, though mobile playbacks that occurred before that date will still be categorized with that value.With this update, mobile playbacks are now classified as either
WATCH
,EMBEDDED
, orEXTERNAL_APP
playbacks, depending on the type of application where the playbacks occur. -
The API now supports
PLAYLIST
as a value for theinsightTrafficSourceType
dimension. The value indicates that video views were referred from a playlist. Previously, these views would have been classified using the dimension'sYT_OTHER_PAGE
category.
July 16, 2013
This update contains the following changes:
-
The API now supports the ability to sort reports by multiple dimensions and metrics. The sample requests document contains a new example, Sorting requests by multiple dimensions/metrics, that demonstrates this functionality. The request retrieves traffic source data and has a
sort
parameter value ofday,-views
. Results are sorted chronologically, but within the result set for each day, the first row contains data for the traffic source that generated the most views, the second row contains data for the source with that generated the next highest amount of views, and so forth. -
The API now supports two new dimensions,
deviceType
andoperatingSystem
, which can be used to retrieve data about the devices where viewers are watching your videos. The API supports reports that use either or both dimensions.-
The
deviceType
report lets you retrieve viewcounts and estimated watch time for different types of devices, including desktop, mobile, and tablet devices. You can also use theoperatingSystem
filter to restrict the device type report to only contain statistics for devices running a specific operating system, such as Android or iOS. -
The
operatingSystem
report lets you retrieve viewcounts and estimated watch time for different operating systems, such as Android, iOS, Linux, and more. You can also use thedeviceType
filter to restrict the operating system report to only contain statistics for a specific type of device, such as mobile devices or tablets.
The new device type and operating system reports are available for channels and for content owners.
-
-
The sample requests document has been updated to include three device reports for channels and three device reports for content owners.
-
The
insightPlaybackLocationType
dimension may return the valueYT_OTHER
, which identifies views that are not classified using one of the dimension's other values.
May 23, 2013
This update contains the following changes:
-
The content owner reports document has been updated to reflect that you can sort the top video report in descending order of earnings to identify videos with the highest earnings. This report is the first one listed in the second table of the User activity and earnings reports section.
May 10, 2013
This update contains the following changes:
-
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy.
May 6, 2013
This update contains the following changes:
-
The API now supports the ability to retrieve watch time metrics –
estimatedMinutesWatched
,averageViewDuration
, andaverageViewPercentage
– in conjunction with other metrics, including view metrics, engagement metrics, earnings metrics, and ad performance metrics.The lists of available channel reports and content owner reports have been updated to reflect this change. (The lists are actually shorter now since the watch time metrics can be retrieved as part of other listed reports.)
The Sample API requests document has also been updated.
-
The reports that use the
insightPlaybackLocationDetail
andinsightTrafficSourceDetail
dimensions have been enhanced in the following ways:-
They now support an optional
country
filter. -
Content owners can now retrieve these reports using any of the following new
filter
combinations. Note that all of these combinations also support the optionalcountry
filter.-
Playback location detail
channel,insightPlaybackLocationType==EMBEDDED
show,insightPlaybackLocationType==EMBEDDED
claimedStatus,insightPlaybackLocationType==EMBEDDED
uploaderType,insightPlaybackLocationType==EMBEDDED
uploaderType,claimedStatus,insightPlaybackLocationType==EMBEDDED
-
Traffic source detail
channel,insightTrafficSourceType
show,insightTrafficSourceType
claimedStatus,insightTrafficSourceType
uploaderType,insightTrafficSourceType
uploaderType,claimedStatus,insightTrafficSourceType
-
-
May 3, 2013
This update contains the following changes:
-
The new Sample API requests document provides examples that demonstrate how to retrieve many different types of reports using the YouTube Analytics API. Each example includes a brief description of the report that the request retrieves and then shows the dimensions, metrics, filters, and sort parameters for the request.
-
The
insightTrafficSourceType
dimension now supportsSUBSCRIBER
as a valid value. This value identifies video views that were referred from feeds on the YouTube homepage or from YouTube subscription features. If you filter based on this traffic source, theinsightTrafficSourceDetail
field will specify the homepage feed or other page from which views were referred.
March 28, 2013
This update contains the following changes:
-
The API now supports two new metrics,
annotationClickThroughRate
andannotationCloseRate
, which are related to viewer interactions with annotations that display during your videos. The lists of channel reports and content owner reports have both been updated to identify the reports that support the new metrics.annotationClickThroughRate
– The ratio of annotations that viewers clicked to the total number of clickable annotation impressions.annotationCloseRate
– The ratio of annotations that viewers closed to the total number of annotation impressions.
March 21, 2013
This update contains the following changes:
-
The API now supports earnings and ad performance metrics as well as new ad performance reports. The metrics and the reports are all accessible only to YouTube content partners who participate in the YouTube Partner Program.
-
The newly supported reports support playback-based ad performance metrics and impression-based ad performance metrics. See the content owner reports documentation for more information about ad performance reports.
-
The newly supported metrics are listed below. The list of content owner reports has been updated to identify the reports, including the two new reports, that support these metrics.
earnings
– Total estimated earnings from all Google-sold advertising sources.grossRevenue
– Estimated gross revenue from Google or DoubleClick partners.primaryAdGrossRevenue
– Estimated gross revenue, summed and classified under the primary ad type for the video playbacks that the report covers, from Google or DoubleClick partners.monetizedPlaybacks
– The number of playbacks that showed at least one ad impression.playbackBasedCpm
– Estimated gross revenue per thousand playbacks.impressions
– The number of verified ad impressions served.impressionBasedCpm
– Estimated gross revenue per thousand ad impressions.
Note: See the metric definitions for complete details.
-
Any request that retrieves earnings or ad performance metrics must send an authorization token that grants access using the new
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
scope.
-
-
The API documentation has been reorganized so that different types of reports are explained on separate pages. As such, there are now separate pages explaining the different types of channel reports and content owner reports.
February 4, 2013
This update contains the following changes:
-
The API's reference guide now has an examples section, which includes code samples that demonstrate how to call the API using the Java, JavaScript, Python, and Ruby client libraries. The JavaScript code sample is the same one discussed in detail in the sample application documentation.
November 14, 2012
This update contains the following changes:
-
The API reference guide now features the API Explorer, which enables you to call the API, see the API request, and retrieve real data in the response.
-
The API supports a number of new reports for both channels and content owners, which are described below. Each report is available as a channel report or a content owner report. The list of available reports has been updated to include these reports. The dimensions and metrics pages have also been updated accordingly.
-
The playback location report specifies the number of video views that took place on different types of pages or applications.
-
The playback location detail report identifies the embedded players that generated the most views for a specified video. It provides a more fine-grained view than the playback location report by identifying the URLs associated with the top embedded players.
-
The traffic source report identifies the number of videos views that originated from different types of referrers.
-
The traffic source detail report identifies the referrers that generated the most views for a specified video and a specified traffic source type. For example, this report could you the related videos that sent the most traffic to a specific video. This report is supported for several traffic sources.
-
Watch time reports provide the amount of time viewers spent watching your content. The reports can aggregate data for a specific time frame – day, previous seven days, previous 30 days, etc. – or country. If a report aggregates data by either day or country, it can also specify the average length of each video view as well as the average percentage of each video that users watched.
-
October 2, 2012
This update contains the following changes:
-
The YouTube Analytics API is now available to all developers. You can activate the API for your project, without having to first request access, from the Services panel in the APIs console.
-
The new Getting Started section outlines the prerequisites and basic steps for building an application that uses the YouTube Analytics API.
September 12, 2012
This update contains the following changes:
-
The new understanding quota usage section provides guidelines for optimizing your API quota usage. The API server calculates a query cost for each request, and that cost is deducted from your API usage quota. Since different types of reports may have greatly different query costs, you should plan to use your quota efficiently, and your application should only request the metrics and data that it actually needs.
-
The temporal dimensions section has been updated to explain that those dimensions indicate that an Analytics report should aggregate data based on a time period. The API now supports the following additional temporal dimensions:
7DayTotals
– Data in the report will be aggregated so that each row contains data for a seven-day period.30DayTotals
– Data in the report will be aggregated so that each row contains data for a 30-day period.month
– Data in the report will be aggregated by calendar month.
Similarly, the available reports section has been updated to reflect the API's support for reports that use these dimensions.
-
The reporting entity dimensions section has been updated to note that API requests to retrieve content owner reports must filter data using either one of these dimensions (
video
,channel
, orshow
) or a supported combination of theclaimedStatus
anduploaderType
dimensions. -
The API now supports two new sorting options for top-video reports. These reports, which are available as channel reports or content owner reports, contain metrics (views, comments, likes, etc.) on a per-country basis and break down those metrics by video. You can now sort these reports based on the number of users who subscribed to or unsubscribed from a channel from the video's watch page.
-
The definitions of the
subscribersGained
andsubscribersLost
metrics have been updated to explain that a channel can gain or lose subscribers in several places, including the video watch page, the channel page, and the guide that appears on the YouTube home page. When these metrics appear in a video-specific report, they only include statistics from the specified video's watch page.