This page lists API changes and documentation updates for both the YouTube Reporting API and the YouTube Analytics API. Both APIs enable developers to access YouTube Analytics data, albeit in different ways.
Subscribe to this changelog
.
April 7, 2024
The YouTube Analytics (Targeted Queries) API has several updates related to content owner
playlist reports. The updates are the same as the updates related to channel playlist reports,
which were announced on January 19, 2024.
The following revision history entry provides nearly
the same information as the entry from January 19, 2024. Note, however, that content owner
playlist reports will support the
isCurated
dimension until
December 31, 2024, while the dimension will be supported for channel playlist reports until
June 30, 2024.
-
Note:
This is a deprecation announcement.
The
isCurated
dimension has been deprecated for content owner playlist reports. It will no longer be
supported on or after December 31, 2024. The definition of that dimension has been updated
accordingly.
To preserve backward compatibility when you remove the
isCurated
dimension, you must also update your code to retrieve the
playlistViews
metric
instead of the
views
metric for playlist reports only. Since the
views
metric is still supported for playlist reports, albeit with a different meaning, the API will
still return data if you do not update the metric name. Of course, you can modify your application
to retrieve and display both
views
and
playlistViews
.
In addition to the
isCurated
dimension, the following API functionality is
no longer supported in the new reports:
- Location filters, such as
continent
and
subcontinent
are not
supported for the new channel playlist reports.
- The
redViews
and
estimatedRedMinutesWatched
metrics are no longer
supported for the new channel playlist reports. These metrics have not been available in YouTube Studio,
so this change aligns API functionality with the functionality available in the Studio application.
- The
subscribedStatus
and
youtubeProduct
dimensions are no longer
supported as filters for channel playlist reports. These filters have not been available in
YouTube Studio, so this change aligns API functionality with the functionality available in
the Studio application.
-
The
playlist reports
section of the content owner reports documentation has been updated to more thoroughly explain
the types of metrics that are supported for playlist reports:
- Aggregated video metrics
provide user activity and impression metrics that are aggregated for all videos in the
content owner's playlists that are also owned by that content owner. Aggregated video metrics are
supported only for API requests that do not use the
isCurated
dimension.
- In-playlist metrics
reflect user activity and engagement in the context of the playlist page. These metrics
include data for will also include views from non-owned videos in the playlist but
only when those views occurred in the playlist context.
- The
supported playlist metrics
section identifies the aggregated video metrics and in-playlist metrics that are
supported for playlist reports.
-
The following new
in-playlist
metrics are supported for playlist reports for
content owners. Note that these metrics are supported only if the API request to retrieve
the reports does
not
use the
isCurated
dimension. See the
metrics
documentation for
definitions of each metric:
-
The behavior of the
views
metric now depends on whether the API request that retrieved the playlist report used the
isCurated
dimension:
- When a request includes the
isCurated
dimension, the
views
metric is an in-playlist
metric that indicates the number of times that videos were viewed in the context of the
content owner's playlists.
- When a request does not include the
isCurated
dimension, the
views
metric is an aggregated video metric that specifies the total number
of times that videos in the content owner's playlists were viewed, regardless of whether those
views took place in the playlist context. The aggregated total includes only views of
videos that are owned by the content owner associated with the channel that owns the playlist.
In these reports, which do not use the
isCurated
dimension, the
playlistViews
metric indicates the number of times that videos were viewed
in the playlist context. That metric counts views for all videos in the playlist,
regardless of which channel owns them.
-
For each playlist report, the
content owner reports
documentation now includes tables showing supported metrics for that report depending on
whether the API request includes the
isCurated
dimension. Refer to the section defining
time-based playlist reports
for an example.
January 19, 2024
The YouTube Analytics (Targeted Queries) API has several updates related to channel playlist
reports. The updates include a deprecated dimension and several new and updated metrics:
-
Note:
This is a deprecation announcement.
The
isCurated
dimension has been deprecated for channel reports. It will no longer be supported on or
after June 30, 2024. The definition of that dimension has been updated accordingly.
To preserve backward compatibility when you remove the
isCurated
dimension, you must also update your code to retrieve the
playlistViews
metric
instead of the
views
metric for playlist reports only. Since the
views
metric is still supported for playlist reports, albeit with a different meaning, the API will
still return data if you do not update the metric name. Of course, you can modify your application
to retrieve and display both
views
and
playlistViews
.
In addition to the
isCurated
dimension, the following API functionality is
no longer supported in the new reports:
- Location filters, such as
continent
and
subcontinent
are not
supported for the new channel playlist reports.
- The
redViews
and
estimatedRedMinutesWatched
metrics are no longer
supported for the new channel playlist reports. These metrics have not been available in YouTube Studio,
so this change aligns API functionality with the functionality available in the Studio application.
- The
subscribedStatus
and
youtubeProduct
dimensions are no longer
supported as filters for channel playlist reports. These filters have not been available in
YouTube Studio, so this change aligns API functionality with the functionality available in
the Studio application.
-
The
playlist reports
section of the channel reports documentation has been updated to more thoroughly explain
the types of metrics that are supported for playlist reports:
- Aggregated video metrics
provide user activity and impression metrics that are aggregated for all videos in the
channel's playlists that are also owned by that channel. Aggregated video metrics are
supported only for API requests that do not use the
isCurated
dimension.
- In-playlist metrics
reflect user activity and engagement in the context of the playlist page. These metrics
include data for will also include views from non-owned videos in the playlist but
only when those views occurred in the playlist context.
- The
supported playlist metrics
section identifies the aggregated video metrics and in-playlist metrics that are
supported for playlist reports.
-
The following new
in-playlist
metrics are supported for playlist reports for channels.
These metrics are not yet supported for content owner reports. Note that these metrics are
supported only if the API request to retrieve the reports does
not
use the
isCurated
dimension. See the
metrics
documentation for
definitions of each metric:
-
The behavior of the
views
metric now depends on whether the API request that retrieved the playlist report used the
isCurated
dimension:
- When a request includes the
isCurated
dimension, the
views
metric is an in-playlist
metric that indicates the number of times that videos were viewed in the context of the
channel's playlists.
- When a request does not include the
isCurated
dimension, the
views
metric is an aggregated video metric that specifies the total number
of times that video in the channel's playlists were viewed, regardless of whether those
views took place in the playlist context. The aggregated total includes only views of
videos that are owned by the channel that owns the playlist.
In these reports, which do not use the
isCurated
dimension, the
playlistViews
metric indicates the number of times that videos were viewed
in the playlist context. That metric counts views for all videos in the playlist,
regardless of which channel owns them.
-
For each playlist report, the
channel reports
documentation now includes tables showing supported metrics for that report depending on
whether the API request includes the
isCurated
dimension. Refer to the section defining
time-based playlist reports
for an example.
December 04, 2023
The YouTube Analytics (Targeted Queries) API has been updated to merge two
insightTrafficSourceType
dimension values. Previously, the dimension differentiated between videos played as part of a playlist
(
PLAYLIST
) and views that originated from a page that lists all of the videos in a playlist
(
YT_PLAYLIST_PAGE
). Going forward, both type of views will be associated with the
PLAYLIST
dimension value.
December 15, 2022
The YouTube Analytics (Targeted Queries) API supports two new dimensions and one new report:
-
A new report provides user activity by city. This report is available for
channels
and
content owners
.
This report contains the new
city
dimension, which identifies YouTube's estimate of the city where the user activity took place.
-
The new
creatorContentType
dimension identifies the type of YouTube content that is associated with the user activity
metrics in the data row. Supported values are
LIVE_STREAM
,
SHORTS
,
STORY
, and
VIDEO_ON_DEMAND
.
The
creatorContentType
dimension is supported as an optional dimension for all
channel and content owner video reports.
-
The YouTube Analytics API
sample requests
guide now includes examples for both new dimensions.
-
References to the
7DayTotals
and
30DayTotals
dimensions have been
removed from the documentation. The deprecation of these dimensions was announced in October
2019.
August 26, 2022
The YouTube Analytics (Targeted Queries) API and the YouTube Reporting (Bulk Reports) API both
support a new traffic source detail value:
- In the YouTube Analytics API (Targeted Queries) API, if the
insightTrafficSourceType
dimension's value is
SUBSCRIBER
, then the
insightTrafficSourceDetail
value can be set to
podcasts
, which indicates that the traffic was referred from the
Podcasts destination page.
- In the YouTube Reporting (Bulk Reports) API, if the
traffic_source_type
dimension's value is
3
, then the
traffic_source_detail
value
can be set to
podcasts
, which indicates that the traffic was referred from the
Podcasts destination page.
February 11, 2022
The set of valid values for the
gender
dimension will be changing on or after August
11, 2022. This might be a backward-incompatible change in your API implementation. In keeping with the
Backward
Incompatible Changes
section of the YouTube API Services Terms of Service, this change is
being announced six months before it will go into effect. Please update your API implementation
prior to August 11, 2022, to ensure a seamless transition to the new set of values.
The specific changes being made are:
- In the YouTube Analytics (Targeted Queries) API, the
gender
dimension currently
supports two values:
female
and
male
. On or after August 11, 2022, that
dimension will support three values:
female
,
male
, and
user_specified
.
- In the YouTube Reporting (Bulk Reports) API, the
gender
dimension currently
supports three values:
FEMALE
,
MALE
, and
GENDER_OTHER
.
On or after August 11, 2022, the set of supported values will change to be
FEMALE
,
MALE
, and
USER_SPECIFIED
.
February 9, 2022
Two metrics have been updated to exclude
looping clips
traffic as of
December 13, 2021. This change affects both the YouTube Analytics (Targeted Queries) API and the
YouTube Reporting (Bulk Reports) API.
February 2, 2022
This YouTube Reporting (Bulk Reports) API supports a new traffic source dimension value that
indicates that the views originated from
Live Redirects
:
- In the YouTube Reporting (Bulk Reports) API, the
traffic_source_type
dimension supports the value
28
.
For this traffic source type, the
traffic_source_detail
dimension specifies the channel ID from which the viewer was referred.
September 23, 2020
This YouTube Analytics (Targeted Queries) API and the YouTube Reporting (Bulk Reports) API both
support a new traffic source dimension value that indicates that the viewer was referred by
swiping vertically in the YouTube Shorts viewing experience:
- In the YouTube Analytics API (Targeted Queries) API, the
insightTrafficSourceType
dimension supports the value
SHORTS
.
- In the YouTube Reporting (Bulk Reports) API, the
traffic_source_type
dimension supports the value
24
.
The traffic source detail dimension ?
insightTrafficSourceDetail
in the YouTube Analytics API or
traffic_source_detail
in the YouTube Reporting API ? is not populated for this new traffic source type.
July 20, 2020
This update covers two changes that affect the YouTube Analytics (Targeted Queries) API:
- The maximum size of a
YouTube Analytics reporting
group
has increased from 200 to 500 entities.
- The
reports.query
method's
filters
parameter identifies a list of filters that should be applied when retrieving YouTube Analytics
data. The parameter supports the ability to specify multiple values for the
video
,
playlist
,
and
channel
filters, and the
maximum number of IDs that can be specified for those filters has increased from 200 to 500 IDs.
February 13, 2020
This update contains the following changes related to the YouTube Analytics (Targeted Queries)
API and YouTube Reporting (Bulk Reports) API. You can learn more about these changes in the
YouTube Help Center
.
In both APIs, the set of possible traffic source detail values for notifications
is changing.
In
targeted queries
,
notifications are reported as
insightTrafficSourceType=NOTIFICATION
. In
bulk reports
,
notifications are reported as
traffic_source_type=17
.
The new values split notifications related to uploaded videos and live streams, previously
reported as
uploaded
, into two categories:
uploaded_push
- Views originated from push notifications sent to
subscribers when a video was uploaded
uploaded_other
- Views originated from non-push notifications, such as
email or Inbox notifications, sent to subscribers when a video was uploaded.
These values are returned for the time range starting 2020-01-13 (January 13, 2020).
Also, as a reminder, these values do not represent notifications themselves, but rather the traffic
sources that drove certain YouTube views. For example, if a report row indicates
views=3
,
traffic_source_type=17
(
NOTIFICATION
), and
traffic_source_detail=uploaded_push
, the row is indicating that three views
resulted from viewers clicking on push notifications sent when the video was uploaded.
October 15, 2019
This update contains the following changes related to the YouTube Analytics (Targeted Queries) API:
-
Note:
This is a deprecation announcement.
YouTube is removing support for the
7DayTotals
and
30DayTotals
dimensions. You can still retrieve data using those dimensions until April 15, 2020. On or after that date, attempts to retrieve reports using the
7DayTotals
or
30DayTotals
dimension will return an error.
Note that users can reproduce some of the data for these dimensions by querying using the
day
dimension and aggregating or deriving data across seven- or 30- day periods. For example:
- The number of views for a seven-day period can be calculated by aggregating the number of views from each day of that period.
- The viewerPercentage for a seven-day period can be calculated by multiplying the number of views that occurred each day times the viewerPercentage for that day to get the number of viewers who were logged in when watching the video that day. Then, the number of logged-in viewers can be added for the whole period and divided by the total number of views for that period to get the viewerPercentage for the whole period.
- The number of unique viewers for a seven-day period cannot be calculated since the same viewer could be calculated as a unique viewer on different days. However, you might be able to use the
month
dimension instead of the
30DayTotals
dimension to extrapolate data about the number of unique viewers over a 30-day period. Note that the
month
dimension refers to calendar months whereas the
30DayTotals
dimension calculates 30-day periods based on the specified start and end date.
June 27, 2019
This update contains the following changes related to the YouTube Analytics (Targeted Queries) API:
-
Since version 1 of the API is now fully deprecated, the documentation has been updated to remove references to that version, including the deprecation notice and the migration guide explaining how to update to version 2.
November 1, 2018
This update contains the following changes related to the YouTube Analytics (Targeted Queries) API:
-
Version 1 of the API is now deprecated. If you have not done so already, please update your API clients to use version 2 of the API as soon as possible to minimize service disruptions. See the
migration guide
for more details.
Note that the schedule for this deprecation was originally announced on
April 26, 2018
.
September 17, 2018
This update contains the following changes related to the YouTube Analytics (Targeted Queries) API:
-
The new
data anonymization
section in the
Data Model
overview document explains that some YouTube Analytics data is limited when metrics do not meet a certain threshold. This can happen in a variety of cases. 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.
The new section also includes a discussion of the types of data that might be limited in YouTube Analytics reports.
-
The
channel reports
and
content owner reports
documents have been updated to reflect the fact that the
redViews
and
estimatedRedMinutesWatched
metrics are no longer supported for playback location, traffic source, and device type/operating system reports.
June 18, 2018
This update contains the following changes to the YouTube Analytics (Targeted Queries) API:
- The scope requirements for the following methods have changed:
May 23, 2018
This update contains the following changes to the YouTube Analytics (Targeted Queries) API:
- The API Overview contains a new section,
aggregate metrics and deleted items
, which explains how API responses handle data associated with deleted resources, such as videos, playlists, or channels.
- The API Overview's
best practices
section has been updated to remind you that you can 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.
May 22, 2018
This update contains the following changes related to the YouTube Reporting (Bulk Reports) API:
- The following changes are currently scheduled to go into effect in July 2018, and the new policies apply globally to all reports and reporting jobs.
-
After the change, most API reports, including backfill reports, will be available for 60 days from the time that they are generated. However, reports containing historical data will be available for 30 days from the time they are generated.
Prior to this announcement, all API reports have been available for 180 days from the time that they were generated. To be clear, when this policy change goes into effect, historical data reports that are more than 30 days old will also no longer be accessible via the API. All other reports that are more than 60 days old will also no longer be accessible. As such, the documentation now states that reports created prior to the policy change will be available for
up to
180 days.
-
After the change, when you schedule a reporting job, YouTube will generate reports from that day forward and covering the 30-day period prior to the time the job was scheduled. Prior to the change, when you schedule a reporting job, YouTube will generate reports covering the 180-day period prior to the time that the job was scheduled.
-
The
best practices
section has been updated to remind you that you can use the
YouTube Data API
to retrieve additional metadata for resources identified in reports. 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.
-
The
Report characteristics
section has been updated to note that even though report data is not filtered, reports that contain data for a time period on or after June 1, 2018, will not contain any references to YouTube resources that were deleted at least 30 days prior to the date the report was generated.
-
The
historical data
section of the API overview has been updated to note that when you schedule a new reporting job, the historical reports are typically posted within a couple of days. Previously, the documentation stated that it could take up to 30 days for such reports to be available.
-
The
backfill data
section of the API overview has been updated to more clearly define
backfill data
as a data set that replaces a previously delivered set.
April 26, 2018
Version 2 of the YouTube Analytics (Targeted Queries) API (v2) is now publicly available. The following list identifies product and documentation changes related to the new API version:
-
The v2 API is almost identical to the v1 API. However, you will likely need to update your code to reflect the changes listed below. All of these changes are explained in detail in the new
migration guide
.
- The API's version has changed from
v1
to
v2
.
- The base URL for API requests has changed from
https://www.googleapis.com/youtube/analytics/v1
to
https://youtubeanalytics.googleapis.com/v2
.
- Several parameters for the
reports.query
method have updated names. Specifically, parameter names that contain hyphens, like
end-date
in the v1 API use camel case (
endDate
) rather than hyphens in the v2 API. This change makes parameter names consistent throughout the API since the API's methods for creating and managing groups already used camel casing for parameter names.
- The v2 API does not support batch requests sent to Google's global HTTP batch endpoint (
www.googleapis.com/batch
). If you are sending batch requests in the v2 API, you need to use the endpoint
https://youtubeanalytics.googleapis.com/v2
instead.
In addition, a few v1 features are not supported in the v2 API:
- The
reports.query
method no longer supports the
alt
,
quotaUser
, and
userIp
request parameters.
- The v2 API does not provide a batch endpoint that supports batches comprised of requests to different APIs. (A batch can be comprised of requests to different methods of the same API, however.) This deprecation is not specific to the YouTube Analytics API as Google is deprecating the global batch endpoint across all of its APIs.
- The v2 API does not support the JSON-RPC protocol, which was supported in API v1. Again, this deprecation is not specific to the YouTube Analytics API.
-
Note:
This is a deprecation announcement.
Version 1 of the API (v1) is now deprecated and will be supported until October 31, 2018. All requests to the v1 API will stop working after that date. As such, please be sure to upgrade to the v2 API no later than October 31, 2018, to avoid any interruption in your ability to access YouTube Analytics data via the API.
February 21, 2018
This update contains the following changes to the YouTube Analytics (Targeted Queries) API:
- Viewer demographic reports, which aggregate viewing statistics based on viewers' age group and gender, no longer support the
youtubeProduct
dimension, which identifies the YouTube service on which the user activity occurred.
January 18, 2018
This update contains the following changes:
December 20, 2017
This update contains two changes related to the YouTube Reporting API:
-
The API server now supports gzip compression for requests that download reports. Note that gzip compression is not supported for other types of API requests. Enabling gzip compression reduces the bandwidth needed for each API response. And, while your application will need additional CPU time to uncompress API responses, the benefit of consuming fewer network resources usually outweighs that cost.
To receive a gzip-encoded response, set the
Accept-Encoding
HTTP request header to
gzip
as shown in the following example:
Accept-Encoding: gzip
This functionality is explained in the
API overview
and in the definition of the
report
resource's
downloadUrl
property.
-
The documentation of the
age group
and
gender
dimensions has been corrected to show the actual values that the API returns for those dimensions. Note that this is a documentation correction and does not reflect a change in API functionality or behavior. Specifically, the following values have changed:
- Values for the
age_group
dimension use uppercase letters, contain underscores between the word
AGE
and the numbers in the age group, and use underscores instead of hyphens. As such, values like
age13-17
and
age18-24
have been corrected to
AGE_13_17
and
AGE_18_24
, respectively.
- Values for the
gender
dimension use uppercase letters. Thus, the values
female
,
male
, and
gender_other
have been corrected to
FEMALE
,
MALE
, and
GENDER_OTHER
.
August 10, 2017
On August 10, 2016, this documentation announced the deprecation of the YouTube Analytics API's
earnings
metric. (At the same time, the API added support for a new metric, named
estimatedRevenue
, that provides the same data.)
Since the
earnings
metric was a core metric, it was supported for one year from the date of the announcement. Now that that yearlong period has ended, however, the
earnings
metric is no longer supported. As a result, API requests that specify the
earnings
metric now return a
400
HTTP response code. If you haven't already updated your app to use the
estimatedRevenue
metric instead of the
earnings
metric, please do so as soon as possible.
The API documentation has been updated to remove remaining references to the
earnings
metric.
July 6, 2017
This update contains the following changes:
May 24, 2017
All reporting jobs for the following YouTube Reporting API reports have been deleted:
content_owner_ad_performance_a1
content_owner_asset_estimated_earnings_a1
content_owner_estimated_earnings_a1
These report types were announced as deprecated on
June 22, 2016
, and reports were no longer generated for those report types after September 22, 2016. Previously generated reports were still available for 180 days from the time they were generated. Thus, some reports were accessible as late as March 22, 2017. However, since the reports are no longer available, the jobs associated with the reports are not needed either.
May 22, 2017
This update contains the following changes:
March 28, 2017
Channel owners who can access revenue data through YouTube Analytics in Creator Studio can now also access that revenue data via the YouTube Analytics API:
-
The API supports the following revenue-related metrics:
These metrics are supported for the following reports:
-
Channel owners can also now retrieve an
ad performance report
, which supports the
adType
dimension as well as the optional
day
dimension.
-
The YouTube Analytics API
sample requests
guide now includes a section for
channel revenue reports
.
March 17, 2017
This update contains the following changes:
March 3, 2017
This update contains the following changes:
February 8, 2017
The YouTube Analytics API now supports the optional
include-historical-channel-data
parameter. Note that this parameter is only relevant when retrieving
content owner reports
.
The parameter allows a content owner to indicate that an API response should include channels' watch time and view data from the time period prior to when the channels were linked to the content owner. The default parameter value is
false
, which means that, by default, the API response only includes watch time and view data from the time that channels were linked to the content owner.
These rules also apply if the API request retrieves data for multiple channels:
- If the parameter value is
false
, then the watch time and views data returned for any given channel is based on the date that that channel was linked to the content owner.
It is important to remember that different channels might have been linked to a content owner on different dates. If the API request is retrieving data for multiple channels and the parameter value is
false
, then the API response contains watch time and view data based on the linking date for each respective channel.
- If the parameter value is
true
, then the response returns watch time and view data for all channels based on the start and end dates specified in the API request.
December 15, 2016
The following YouTube Reporting API reports are no longer supported and have been removed from the documentation. A newer version of each report is available. (The
deprecation announcement
for these reports was made on September 15, 2016.)
-
Channel reports
-
Content owner reports
The list of
current report types
in the API reference documentation has also been updated.
November 11, 2016
This update contains the following changes:
The YouTube Reporting API supports three new end screen reports as well as new dimensions and metrics for those reports. The reports provide impression and click-through statistics for the end screens that display after a video stops playing.
-
End screen reports
- The end screen report for
channel videos
contains statistics for all of a channel's videos.
- The end screen report for
content owner videos
contains statistics for videos on any of a content owner's channels.
- The end screen report for
content owner assets
contains statistics for the assets associated with the videos after which the end screens display.
-
End screen dimensions
End screen metrics
Note:
Data for end screen metrics is available as of May 1, 2016.
The YouTube Help Center contains more detailed information about
adding end screens to your videos
.
-
The following reports are no longer supported and have been removed from the documentation. A newer version of each report is available. (The
deprecation announcement
for these reports was made on June 22, 2016.)
November 8, 2016
This update contains the following changes to the YouTube Analytics API:
-
The metrics in the following list are fully deprecated and no longer supported. As announced on August 10, 2016, new metrics referring to the same data are already supported. The table below shows the deprecated metric name and the new metric name:
October 27, 2016
YouTube now automatically generates a set of system-managed ad revenue reports for content owners that have access to the corresponding reports in the
Reports
section of YouTube's Creator Studio. The new system-managed API reports are designed to provide programmatic access to data that is also available in the manually downloadable Creator Studio reports.
The
system-managed reports overview
provides a brief overview of the new reports and explains the process for retrieving them via the API. This process is slightly different from that for retrieving bulk reports for YouTube Analytics since partners do not need to schedule jobs to generate the reports.
The
reportType
resource's
id
property has been updated to include a list of the system-managed reports that you can access via the API:
- Monthly, worldwide ad revenue per video
- Daily, per-country ad revenue per video
- Monthly, worldwide ad revenue per asset
- Daily, per-country ad revenue per asset
- Claims (this report does not contain revenue data)
September 27, 2016
Note:
This is a deprecation announcement.
The YouTube Analytics API's
uniques
metric has been deprecated. This is not a core metric and it will be supported until October 31, 2016.
September 15, 2016
This update contains the following YouTube Reporting API changes:
-
The API supports two new metrics related to YouTube Red viewership:
red_views
: The number of times that a video was viewed by YouTube Red members.
red_watch_time_minutes
: The number of minutes that YouTube Red members watched a video.
-
The API supports new versions of 20 reports. All of the new versions support the new
red_views
and
red_watch_time_minutes
metrics.
For each report, the number in the new report type ID is one number higher than in the old report type ID. (The old versions of these reports are now deprecated as described later in this revision history.) For example, the
channel_basic_
a1
report is now deprecated and has been replaced by the
channel_basic_
a2
report.
The following lists identify the new report type IDs:
-
Note:
This is a deprecation announcement.
Note that if you already have jobs to create any of the older versions of the reports listed above, you need to create new jobs for the renamed reports. In conjunction with the release of the new report versions, the following report versions have been deprecated:
channel_basic_a1
channel_province_a1
channel_playback_location_a1
channel_traffic_source_a1
channel_device_os_a1
channel_subtitles_a1
channel_combined_a1
content_owner_basic_a2
content_owner_province_a1
content_owner_playback_location_a1
content_owner_traffic_source_a1
content_owner_device_os_a1
content_owner_subtitles_a1
content_owner_combined_a1
content_owner_asset_basic_a1
content_owner_asset_province_a1
content_owner_asset_playback_location_a1
content_owner_asset_traffic_source_a1
content_owner_asset_device_os_a1
content_owner_asset_combined_a1
If you have jobs for any of those reports, you should not expect YouTube to generate new reports for those jobs after December 15, 2016. Generated reports will still be available for 180 days from the time they were generated.
August 19, 2016
This update contains the following YouTube Reporting API change:
-
The
content_owner_basic_a1
report has been fully deprecated and removed from the documentation. YouTube will no longer generate new reports of that type, though reports that were already generated will still be available for 180 days from the time they were generated.
The
content_owner_basic_a1
report's replacement is the
content_owner_basic_a2
report as explained in the
revision history entry for May 19, 2016
.
August 11, 2016
This update contains the following changes:
-
The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the
YouTube Engineering and Developers Blog
, provides a rich set of updates to the current Terms of Service. In addition to the
Updated Terms
, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.
The full set of new documents is described in the
revision history for the Updated Terms
. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.
August 10, 2016
This update includes the following changes:
July 18, 2016
This update includes the following changes:
June 28, 2016
The YouTube Analytics API documentation has been updated to reflect support for
card metrics
in numerous
channel
and
content owner
reports. The newly supported metrics are:
The metrics are supported in the following types of reports:
June 22, 2016
This update contains the following YouTube Reporting API changes. The first change pertains to the API in general, and the remaining changes only affect
content owner reports
:
-
The
Report characteristics
section of the API overview has been updated to clarify that reports are available via the API for 180 days from the time that they are generated.
Previously, the documentation stated that reports are available for a period of up to 180 days prior to the date that the API request is sent. While also technically true, the original text was, at best, rather confusing.
-
The API supports new versions of three reports. Two of those reports also contain new and renamed metrics:
-
The
content_owner_ad_rates_a1
report is the new version of the
content_owner_ad_performance_a1
report. The newly renamed report is identical to the previous version.
-
Two reports that have new versions have been renamed:
- The new version of the
content_owner_estimated_earnings_a1
report is named
content_owner_estimated_revenue_a1
.
- The new version of the
content_owner_asset_estimated_earnings_a1
report is named
content_owner_asset_estimated_revenue_a1
.
Both newly renamed reports differ from their predecessors in the following ways:
Note that if you already have jobs to create any of the older versions of these reports, you need to create new jobs for the renamed reports. In conjunction with the release of the new report versions, the
content_owner_ad_performance_a1
,
content_owner_estimated_earnings_a1
, and
content_owner_asset_estimated_earnings_a1
reports have been deprecated.
If you have jobs for any of those reports, you should not expect YouTube to generate new reports for those jobs after September 22, 2016. Generated reports will still be available for 180 days from the time they were generated.
-
The definition of the
reportType
resource's
id
property has been updated to reflect the current set of available reports.
-
The names of two metrics have been corrected in the documentation to match the names that appear in reports. This is purely a documentation fix and does not reflect a change in actual report contents:
- The
estimated_partner_adsense_revenue
metric's name has been updated to
estimated_partner_ad_sense_revenue
. Note, however, that this metric only appears in two reports that are being deprecated with this update. As described above, this metric has been renamed
estimated_partner_ad_auction_revenue
in newer versions of those reports.
- The
estimated_partner_doubleclick_revenue
metric's name has been updated to
estimated_partner_double_click_revenue
. Again, note that this metric only appears in two reports that are being deprecated with this update. As described above, this metric has been renamed
estimated_partner_ad_reserved_revenue
in newer versions of those reports.
-
The
dimensions
documentation for the Reporting API has been updated to no longer list the
elapsed_video_time_percentage
and
audience_retention_type
properties. These dimensions are not currently supported by any reports available through the API.
May 19, 2016
This update contains the following YouTube Reporting API changes:
-
The API supports a new version of the
user activity report for content owners
. The report type ID for the new report is
content_owner_basic_a2
. Unlike the previous version of the report,
content_owner_basic_a1
, the new version supports the
likes
and
dislikes
metrics.
If you already have a job to create the
content_owner_basic_a1
report, you still need to create a new job for the
content_owner_basic_a2
report. YouTube is not automatically migrating content owners to the new report version or automatically creating a job to generate the new report version. In some implementations, the appearance of a new, unexpected job could be a breaking change.
In conjunction with the release of the new report, the
content_owner_basic_a1
report has been
deprecated
. If you have a job for that report, you should not expect YouTube to generate new reports for that job after August 19, 2016. Generated reports will still be available for 180 days from the time they were generated.
-
The
reportType
,
job
, and
report
resources all support a new property that identifies whether the associated resource represents a deprecated report type:
-
The
reportType
resource's
deprecateTime
property specifies the date and time that the report type will be deprecated. This property only has a value for reports that have been announced as deprecated, and the value represents the date when YouTube will stop generating reports of that type.
After a report type is announced as deprecated, YouTube generates reports of that type for another three months. For example, this update on May 19, 2016, announces the deprecation of the
content_owner_basic_a1
report. Thus, the
deprecateTime
for that report type specifies a time on August 19, 2016, after which YouTube will stop generating reports of that type.
-
The
job
resource's
expireTime
property specifies the date and time that the job expired or will expire. This property has a value if the report type associated with the job has been deprecated or if reports generated for the job have not been downloaded for a prolonged period of time. The date marks the time after which YouTube no longer generates new reports for the job.
-
The
report
resource's
jobExpireTime
property specifies the date and time that the job that is associated with the report either expired or will expire. This property contains the same value as the
expireTime
property in the
job
resource, as described in the previous item in this list.
-
The
jobs.create
method now returns a
400
HTTP response code (
Bad Request
) if you try to create a job for a deprecated report. In addition, the method's documentation now lists several other reasons that cause an API request to fail.
April 12, 2016
This update contains the following changes, all of which only affect the YouTube Reporting API:
-
YouTube now generates data covering the 180-day period prior to the time a reporting job was first scheduled. Previously, the Reporting API did not deliver any historical data. This change affects all jobs, including those created prior to this announcement.
Historical reports are posted as soon as they are available, though it takes roughly one month for all of the historical data to be posted for a job. So, a month after scheduling a reporting job, you will have access to around seven months of data. (All of the historical data for jobs created prior to this announcement should be posted within a month of the announcement.)
Note that historical data is only available as of July 1, 2015. As a result, jobs created before December 28, 2015, will have less than 180 days of historical data.
These change are all explained in the new
historical data
section of the Reporting API overview.
-
The
report characteristics
section of the YouTube Reporting API overview has been updated with the following changes:
-
The documentation now states that reports are available for a period of
180 days after they are generated
and, therefore, available for API clients to download. Previously, the documentation stated that reports were available for a period of up to six months prior to the date that the API request is sent.
-
The documentation has been updated to reflect the fact that the API now generates downloadable reports for days on which no data was available. Those reports will contain header rows but will not contain additional data.
-
The YouTube Reporting API will soon support a set of automatically generated, system-managed reports that contain ad revenue data or YouTube Red subscription revenue data. The reports will be available to content owners who can already access manually downloadable revenue reports in the YouTube
Creator Studio
. Thus, the new API functionality will provide programmatic access to that data.
The following API changes are being announced now in preparation for the launch of system-managed reports:
-
The
job
resource's new
systemManaged
property indicates whether the resource describes a job that generates system-managed reports. YouTube automatically generates system-managed reports for YouTube content owners, and content owners cannot modify or delete jobs that create those reports.
-
The
jobs.list
method's new
includeSystemManaged
parameter indicates whether the API response should include jobs for system-managed reports. The parameter's default value is
false
.
-
The
jobs.reports.list
method's new
startTimeAtOrAfter
parameter indicates that the API response should only contain reports if the earliest data in the report is on or after the specified date. Similarly, the
startTimeBefore
parameter indicates that the API response should only contain reports if the earliest data in the report is before the specified date.
Unlike the method's
createdAfter
parameter, which pertains to the time that the report was created, the new parameters pertain to the data in the report.
-
The
reportType
resource's new
systemManaged
property indicates whether the resource describes a system-managed report.
-
The
reportTypes.list
method's new
includeSystemManaged
parameter indicates whether the API response should include system-managed reports. The parameter's default value is
false
.
March 28, 2016
The YouTube Reporting API and YouTube Analytics API now return view statistics for several additional sharing services.
- In the YouTube Reporting API, the
sharing_service
dimension supports these new values:
82
: iOS system activity dialog
83
: Google Inbox
84
: Android Messenger
- In the YouTube Analytics API, the
sharingService
dimension supports these new values:
ANDROID_MESSENGER
: Android Messenger
INBOX
: Google Inbox
IOS_SYSTEM_ACTIVITY_DIALOG
: iOS system activity dialog
March 16, 2016
This update contains the following changes, which affect both the YouTube Reporting API and the YouTube Analytics API:
YouTube Reporting API
- The
playback_location_type
dimension supports two new dimension values:
7
: The data pertains to views that took place on the YouTube home page or home screen, in the user's subscription feed, or in another YouTube browsing feature.
8
: The data pertains to views that took place directly on the YouTube search results page.
- The
traffic_source_type
dimension now supports
18
as a dimension value. This value indicates that the video views originated from a page that lists all of the videos in a playlist. This source differs from source type
14
, which indicates that the views occurred while the video was being played as part of a playlist.
YouTube Analytics API
- The
insightPlaybackLocationType
dimension supports two new dimension values:
BROWSE
: The data pertains to views that took place on the YouTube home page or home screen, in the user's subscription feed, or in another YouTube browsing feature.
SEARCH
: The data pertains to views that took place directly on the YouTube search results page.
- The
insightTrafficSourceType
dimension now supports
YT_PLAYLIST_PAGE
as a dimension value. This value indicates that the video views originated from a page that lists all of the videos in a playlist. This source differs from the
PLAYLIST
source type, which indicates that the views occurred while the video was being played as part of a playlist.
February 8, 2016
The list of metrics supported for the YouTube Analytics API has been updated so that
card metrics
are no longer listed as supported metrics for that API. (None of that API's reports had been documented as supporting any of the card metrics.)
Note that you can still retrieve
card metrics
using the YouTube Reporting API, which supports those metrics for numerous
channel
and
content owner
reports.
January 6, 2016
The YouTube Reporting API and YouTube Analytics API both now specifically identify views that occur via a Chromecast device.
- In the YouTube Reporting API, the
operating_system
dimension uses the value
21
to identify views that take place via Chromecast.
- In the YouTube Analytics API, the
operatingSystem
dimension uses the value
CHROMECAST
to identify views that take place via Chromecast.
December 21, 2015
In the documentation, the names of the
annotation_clickable_impressions
and
annotation_closable_impressions
metrics have been updated to match the names being returned in the reports. Previously, the names were documented as
clickable_annotation_impressions
and
closable_annotation_impressions
.
December 18, 2015
European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the
EU User Consent Policy
. We have added a notice of this requirement in our
YouTube API Terms of Service
.
December 15, 2015
This update contains the following changes, all of which affect the YouTube Analytics API:
-
The YouTube Analytics API now supports three new
playback detail dimensions
, which can be used in a variety of channel and content owner reports:
liveOrOnDemand
: This dimension indicates whether the data in the report describes user activity that occurred during a live broadcast.
subscribedStatus
: This dimension indicates whether the user activity metrics in the data are associated with viewers who were subscribed to the video's or playlist's channel.
youtubeProduct
: This dimension identifies the YouTube property on which the user activity occurred. Possible values include the core YouTube website (or YouTube app), YouTube Gaming, and YouTube Kids.
The documentation has been updated to identify new playback detail reports that are available for
channels
and
content owners
. In addition, many other reports have been updated to note that one or more of these dimensions can optionally be used as dimensions and/or filters in those reports.
-
The format of the tables that explain the reports has changed to make it easier for you to identify valid combinations of dimensions, metrics, and filters that can be used to retrieve each report. The table below, which explains the "Device Type" report for channels, shows the new format:
Contents
|
Dimensions:
|
|
Metrics:
|
|
Filters:
|
|
The terminology describing required and optional fields is explained in the documentation for
channel
and
content owner
reports.
-
The YouTube Analytics API now automatically drops entities that the API user cannot retrieve data for from filters that support multiple values (
video
,
playlist
, and
channel
). Previously, the API server would have just returned an error if the API user could not access data for at least one of the specified items.
For example, suppose a user submits an API request in which the
video
filter lists 20 video IDs. The user owns 18 of the videos. However, one videos ID identifies a video owned by another channel, and another ID identifies a video that was deleted and, therefore, no longer exists. In this case, instead of returning an error, the API server now drops the two videos that the user cannot access, and the API response contains data for the 18 videos that the API user owns.
-
If you request data for an empty YouTube Analytics
group
, the API now returns an empty data set rather than an error.
-
The YouTube Analytics API's
groupItems.insert
method now returns an unauthorized (
403
HTTP response code) error if you try to add an entity to a group but you do not have access to that entity. Previously, the API would have allowed you to add the entity to the group, but later returned an unauthorized error when you tried to retrieve report data for that group.
-
The YouTube Analytics API's
groups.list
method now supports pagination. If the API response does not contain all available groups, then the response's
nextPageToken
parameter specifies a token that can be used to retrieve the next page of results. Set the method's
pageToken
parameter to that value to retrieve additional results.
November 10, 2015
This update contains the following changes:
October 29, 2015
This update contains the following changes:
-
The documentation for the YouTube Reporting API's
date
dimension has been corrected to reflect that dates reference the 24-hour period beginning at 12:00 a.m. Pacific time (UTC-8). Previously, the documentation stated that the date began at 12:00 a.m. (GMT).
In addition, the YouTube Analytics API documentation has been updated to note that all date-related dimensions (
day
,
7DayTotals
,
30DayTotals
, and
month
) refer to dates beginning at 12:00 a.m. Pacific time (UTC-8).
-
The YouTube Reporting API's
jobs.reports.list()
method now supports the
createdAfter
query parameter. If specified, this parameter indicates that the API response should only list reports created after the specified date and time, including new reports with backfilled data. Note that the parameter value pertains to the time that the report is created and not the dates associated with the returned data.
The parameter value is a timestamp in RFC3339 UTC "Zulu" format, accurate to microseconds. Example:
"2015-10-02T15:01:23.045678Z"
.
The YouTube Reporting API
best practices
have also been updated to explain how you can use the
createdAfter
parameter to avoid repeatedly processing the same report.
-
The definitions of the
job
resource's
createTime
property and the
report
resource's
startTime
,
endTime
, and
createTime
properties have all been corrected to note that the property values are accurate to microseconds, not nanoseconds. In addition, all of the definitions now accurately reflect that the property value is a timestamp.
October 8, 2015
This update contains the following changes:
-
The documentation for the YouTube Analytics API's
sharingService
dimension has been updated to include a list of possible dimension values. The list includes a number of newly supported services.
The YouTube Reporting API's
sharing_service
dimension's definition has also been updated to list the newly supported values. The enum values that are greater than
59
are the new ones in the list.
September 24, 2015
This update contains the following changes:
-
The new
YouTube Reporting API
retrieves bulk data reports that contain 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 YouTube Reporting API report contains a predefined set of dimensions and metrics. (YouTube Analytics API reports also use metrics and dimensions.) In a report, each row of data has a unique combination of dimension values. You can aggregate data across rows based on dimension values to calculate metrics for individual videos, countries, live videos, subcribed users, and so forth.
You can use the API to schedule reporting jobs, each of which identifies a report that YouTube should generate. Once you have set up a job, YouTube generates a daily report that can be asynchronously downloaded. Each report contains data for a unique, 24-hour period.
-
Although they are different APIs, the YouTube Analytics API and the YouTube Reporting API both enable developers to retrieve YouTube Analytics data. Since the APIs both provide access to similar data sets, the documentation for the two APIs is being published as a single set of documentation.
- The
Guides
tab in the documentation set contains information common to both APIs, including instructions for authorizing API requests.
- The
Bulk reports
tab contains reference documentation and other content specifically for the YouTube Reporting API.
- The
Targeted queries
tab contains reference documentation and other content specifically for the YouTube Analytics API.
- The
Samples
tab lists code samples available for either of the two APIs.
- The
Tools
tab lists additional resources available to help developers implement either of the two APIs.
August 20, 2015
This update contains the following changes:
July 22, 2015
This update contains several changes, all of which only apply to content owners:
-
The new
adEarnings
metric includes total estimated earnings (net revenue) from all Google-sold advertising sources. It is not a core metric. The API supports the
adEarnings
metric for any report that already supported the
earnings
metric.
In addition, the definition of the
earnings
metric has been corrected to reflect the fact that its value includes total estimated earnings from all Google-sold advertising sources as well as from non-advertising sources. Previously, the definition incorrectly indicated that the metric only included earnings from advertising sources.
-
The
primaryAdGrossRevenue
metric has been deprecated. Instead, use the
grossRevenue
metric to retrieve revenue data.
-
In addition to the deprecated
primaryAdGrossRevenue
metric,
ad performance reports
no longer support the
monetizedPlaybacks
and
playbackBasedCpm
metrics. However, several
video reports
do still support those metrics.
June 1, 2015
This update contains the following changes:
-
The API now supports two new metrics for video reports,
videosAddedToPlaylists
and
videosRemovedFromPlaylists
. The lists of video reports for
channels
and
content owners
have both been updated to identify the reports that support the new metrics.
videosAddedToPlaylists
? The number of times that videos in the scope of the query were added to any YouTube playlists. The videos could have been added to the video owner's playlist or to other channels' playlists.
videosRemovedFromPlaylists
? The number of times that videos in the scope of the query were removed from any YouTube playlists. The videos could have been removed from the video owner's playlist or from other channels' playlists.
Both metrics include default playlists like the "Watch Later" playlist. However, they do not count playlists that a video is automatically added to, such as a channel's uploads playlist or a user's watch history. Also note that these metrics reflect the absolute number of additions and deletions. So, if a user adds a video to a playlist, then removes it, and then adds it again, the metrics indicate that the video was added to two playlists and removed from one.
Data for these metrics is available as of October 1, 2014.
March 31, 2015
This update contains the following changes:
March 16, 2015
This update contains the following changes:
-
The new
currency
parameter allows you to retrieve earnings metrics in a currency other than United States dollars (
USD
). If the parameter is set, then the API converts values for the
earnings
,
grossRevenue
,
playbackBasedCpm
, and
impressionBasedCpm
metrics to the specified currency. The values returned are estimates calculated using exchange rates that change on a daily basis.
The parameter value is a three-letter, ISO 4217 currency code. The default value is
USD
. The parameter definition contains a list of supported currency codes.
February 25, 2015
This update contains the following changes:
-
The API now supports the ability to create and manage YouTube Analytics groups as well as the ability to retrieve report data for those groups.
-
Creating and managing groups
This update introduces the
group
and
groupItem
resources for creating and managing groups.
- The
group
resource represents an Analytics group, a custom collection of up to 200 channels, videos, playlists, or assets. The API supports
list
,
insert
,
update
, and
delete
methods for this resource.
- The
groupItem
resource represents an item in an Analytics group. The API supports
list
,
insert
, and
delete
methods for this resource.
So, for example, you could create a group using the
groups.insert
method and then add items to that group using the
groupItems.insert
method.
-
Retrieving report data for a group
The
dimensions
documentation has been updated to include the
group
dimension, which can be used as a filter for many
channel reports
and
content owner reports
. When you use the
group
filter, the API returns data for all of the items in that group. Note that the API does not currently support the ability to create reports for asset groups.
See the
YouTube Help Center
for more information about YouTube Analytics groups.
February 13, 2015
This update contains the following changes:
August 28, 2014
This update contains the following changes:
-
The API now supports the ability to specify multiple values for the
video
,
playlist
,
channel
, and
show
dimensions when those dimensions are used as
filters
. To specify multiple values, set the
filters
parameter value to a comma-separated list of the video, playlist, channel, or show IDs for which the API response should be filtered. The parameter value can specify up to 200 IDs.
If you specify multiple values for the same filter, you can also add that filter to the list of dimensions that you specify for the request. This is true even if the filter is not listed as a supported dimension for a particular report. If you do add the filter to the list of dimensions, then the API also uses the filter values to group results.
See the
filters
parameter definition for complete details about this functionality.
July 16, 2014
This update contains the following changes:
-
When retrieving a channel report, you can now retrieve data for the authenticated user's channel by setting the value of the
ids
parameter to
channel==MINE
. (You can also still set the
ids
parameter to
channel==
CHANNEL_ID
to retrieve data for the specified channel.)
-
The API now supports playlist reports, which contain statistics related to video views that occur in the context of a playlist. Playlist reports are available for
channels
and
content owners
.
All playlist reports support the
views
and
estimatedMinutesWatched
metrics, and some also support the
averageViewDuration
metric.
In addition, all playlist reports support the following new metrics. Note that each of these metrics only reflect playlist views that occurred on the web.
playlistStarts
: The number of times viewers initiated playback of a playlist.
viewsPerPlaylistStart
: The average number of video views that occurred each time a playlist was initiated.
averageTimeInPlaylist
: The estimated average amount of time, in minutes, that a viewer viewed videos in a playlist after the playlist was initiated.
Any request to retrieve a playlist report must use the
isCurated
filter, which must be set to
1
(
isCurated==1
).
-
The API now supports an audience retention report. This report measures a video's ability to retain its audience. The report's new
elapsedVideoTimeRatio
dimension measures the amount of the video that has elapsed for the corresponding metric values:
-
The
audienceWatchRatio
metric identifies the absolute ratio of viewers watching the video at the given point in the video. The ratio is calculated by comparing the number of times a portion of a video has been watched to the total number of views of the video.
Note that a portion of a video could be watched more than once (or not at all) in a given video view. For example, if users rewind and watch the same portion of a video multiple times, then the absolute ratio for that portion of the video the could be greater than
1
.
-
The
relativeRetentionPerformance
metric shows how well a video retains viewers during playbacks in comparison to all YouTube videos of similar length. A value of 0 indicates that the video retains viewers worse than any other video of similar length, while a value of 1 indicates that the video retains viewers better than any other video of similar length. A median value of 0.5 indicates that half of the videos of similar length retain viewers better while half retain viewers worse.
You can also use the
audienceType
filter so that the report only returns data associated with organic views, views from TrueView in-stream ads, or views from TrueView in-display ads. (Organic views are the direct result of user action, such as a search for a video or a click on a suggested video.)
-
The API supports several new metrics related to annotations. The metrics listed below can be retrieved with any reports that previously supported the
annotationClickThroughRate
and
annotationCloseRate
metrics.
All of the new metrics are core metrics and are subject to the
Deprecation Policy
. However, note that data is available for the new metrics as of July 16, 2013. (Data for the
annotationClickThroughRate
and
annotationCloseRate
metrics is available as of June 10, 2012.)
-
GOOGLE_SEARCH
is no longer reported as a separate value for the
insightTrafficSourceType
dimension. Instead, referrals from Google search results are now attributed to the
EXT_URL
traffic source type. As a result, it's also no longer possible to retrieve an
insightTrafficSourceDetail
report that sets the
insightTrafficSourceType
filter to
GOOGLE_SEARCH
.
January 31, 2014
This update contains the following changes:
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 view counts 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 the
filters
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 when
province
is included in the
dimensions
parameter value, the request must also restrict data to the United States by including
country==US
in the
filters
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
, and
subContinent
.
-
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 the
subContinent
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 the
insightTrafficSourceType
value
PROMOTED
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 the
insightPlaybackLocationType
dimension. In conjunction with this update, as of September 10, 2013, playbacks are no longer categorized as
MOBILE
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
, or
EXTERNAL_APP
playbacks, depending on the type of application where the playbacks occur.
-
The API now supports
PLAYLIST
as a value for the
insightTrafficSourceType
dimension. The value indicates that video views were referred from a playlist. Previously, these views would have been classified using the dimension's
YT_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 of
day,-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
and
operatingSystem
, 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 view counts and estimated watch time for different types of devices, including desktop, mobile, and tablet devices. You can also use the
operatingSystem
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 view counts and estimated watch time for different operating systems, such as Android, iOS, Linux, and more. You can also use the
deviceType
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 value
YT_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:
May 10, 2013
This update contains the following changes:
May 6, 2013
This update contains the following changes:
-
The API now supports the ability to retrieve watch time metrics ?
estimatedMinutesWatched
,
averageViewDuration
, and
averageViewPercentage
? 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
and
insightTrafficSourceDetail
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 optional
country
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 supports
SUBSCRIBER
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, the
insightTrafficSourceDetail
field will specify the homepage feed or other page from which views were referred.
March 28, 2013
This update contains the following changes:
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
APIs 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
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
, or
show
) or a supported combination of the
claimedStatus
and
uploaderType
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
and
subscribersLost
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.