История изменений

На этой странице перечислены изменения API и обновления документации для API отчетов YouTube и API YouTube Analytics. Оба API позволяют разработчикам получать доступ к данным YouTube Analytics, хотя и разными способами. Подпишитесь на этот журнал изменений . Подписаться

26 марта 2025 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics и Reporting API:

С 31 марта 2025 г. YouTube изменит порядок подсчета просмотров коротких видео. Раньше просмотр коротких видео засчитывался после того, как короткое видео воспроизводилось в течение определенного количества секунд. Теперь просмотры будут учитывать количество раз, когда ваше короткометражное видео запускалось или воспроизводилось повторно, без каких-либо требований к минимальному времени просмотра. Узнать больше

API YouTube Analytics (целевые запросы) и Reporting (массовые отчеты) будут обновлены со следующими изменениями:

  • Для коротких видео views учитывают количество раз, когда короткометражное видео запускалось или повторялось.
  • Будет доступен новый показатель engagedViews , который будет отражать предыдущую методологию подсчета просмотров.
  • Если вы являетесь владельцем канала или у вас есть разрешение на доступ к данным канала, вы сможете запрашивать как обновленные, так и заинтересованные просмотры.

Целевые запросы будут обновлены к 30 апреля, а массовые отчеты — к 30 июня. До тех пор взгляды будут основываться на старой методологии. Просмотры Shorts и канала не будут соответствовать данным Analytics в Studio.

Кроме того, было отложено ранее объявленное прекращение поддержки отчета Daily Claims (версия 1.0).

Проверьте эту историю изменений, чтобы узнать, когда в API вносились изменения.

3 марта 2025 г.

Это обновление содержит следующие изменения, связанные с API отчетов YouTube:

Примечание. Это объявление об устаревании.

Отчет Daily Claims (версия 1.0) для партнеров устарел. Он перестанет поддерживаться 30 апреля 2025 г. или после этой даты. Определение этого отчета было соответствующим образом обновлено. Вместо этого используйте последний отчет о ежедневных претензиях.

15 ноября 2024 г.

Примечание. Следующее изменение вступает в силу 18 ноября 2024 г.

В документацию по API YouTube Analytics (целевые запросы) добавлена ​​информация о том, что для отчетов об источниках трафика метод reports.query API теперь возвращает ошибку, если произведение количества запрошенных видео на количество дней в диапазоне дат превышает 50 000. Например, запрос, который получает данные для 500 идентификаторов видео, может запрашивать данные максимум за 100 дней.

Это изменение затрагивает отчеты как для каналов , так и для владельцев контента .

Чтобы уменьшить количество строк, возвращаемых запросом, разделите запрос на несколько запросов, которые указывают меньшее количество видео или устанавливают более короткие диапазоны дат. Как правило, массовые отчеты рекомендуются для больших наборов данных.

6 мая 2024 г.

API YouTube Analytics (целевые запросы) поддерживает три новых отчета для каналов:

  • Отчет «Активность пользователей по DMA» — это географический отчет, в котором представлена ​​статистика активности пользователей по назначенным рыночным зонам (DMA). Для этого отчета необходимо установить значение параметра filters country==US .

  • Отчет «Одновременные зрители» показывает количество одновременных зрителей различных частей одного видео в прямом эфире.

  • В отчете «Отмены участников» представлена ​​статистика, показывающая, почему пользователи отменили свое членство в канале .

    В этом отчете используется новое измерениеmembersCancellationSurveyReason, которое указывает membershipsCancellationSurveyReason почему пользователь отменил членство в канале. Он также использует новую membershipsCancellationSurveyResponses , которая показывает, сколько членств в каналах было отменено по этой причине.

Кроме того, отчет «Удержание аудитории» был улучшен и теперь поддерживает три новых показателя:

7 апреля 2024 г.

API YouTube Analytics (целевые запросы) имеет несколько обновлений, связанных с отчетами о плейлистах владельцев контента. Обновления аналогичны обновлениям, связанным с отчетами о плейлистах каналов, о которых было объявлено 19 января 2024 года.

Следующая запись истории изменений содержит почти ту же информацию, что и запись от 19 января 2024 года. Однако обратите внимание, что отчеты о плейлистах владельцев контента будут поддерживать измерение isCurated до 31 декабря 2024 года, а это измерение будет поддерживаться для отчетов о плейлистах каналов до 30 июня 2024 года.

  • Примечание. Это объявление об устаревании.

    Параметр isCurated устарел для отчетов о плейлистах владельцев контента. Он перестанет поддерживаться 31 декабря 2024 г. или после этой даты. Определение этого параметра было соответствующим образом обновлено.

    Чтобы сохранить обратную совместимость при удалении измерения isCurated , вам также необходимо обновить код, чтобы получить метрику playlistViews вместо метрики views только для отчетов по спискам воспроизведения. Поскольку метрика views по-прежнему поддерживается для отчетов по спискам воспроизведения, хотя и с другим значением, API по-прежнему будет возвращать данные, если вы не обновите имя метрики. Конечно, вы можете изменить свое приложение для получения и отображения как views , так и playlistViews .

    Помимо измерения isCurated , в новых отчетах больше не поддерживаются следующие функции API:

    • Фильтры местоположения, такие как continent и subcontinent не поддерживаются для отчетов о новых плейлистах каналов.
    • Метрики redViews и estimatedRedMinutesWatched больше не поддерживаются для отчетов о плейлистах новых каналов. Эти метрики не были доступны в YouTube Studio, поэтому это изменение приводит функциональность API в соответствие с функциями, доступными в приложении Studio.
    • Измерения subscribedStatus и youtubeProduct больше не поддерживаются в качестве фильтров для отчетов о плейлистах канала. Эти фильтры были недоступны в YouTube Studio, поэтому это изменение приводит функциональность API в соответствие с функциональностью, доступной в приложении Studio.

  • Раздел отчетов о плейлистах документации по отчетам владельцев контента был обновлен, чтобы более подробно объяснить типы показателей, которые поддерживаются для отчетов о плейлистах:

    • Агрегированные показатели видео предоставляют показатели активности пользователей и показов, которые суммируются для всех видео в плейлистах владельца контента, которые также принадлежат этому владельцу контента. Агрегированные показатели видео поддерживаются только для запросов API, которые не используют измерение isCurated .
    • Показатели плейлиста отражают активность и вовлеченность пользователей в контексте страницы плейлиста. Эти показатели включают в себя данные о том, что будут также учитываться просмотры видео, не принадлежащих вам, в плейлисте, но только тогда, когда эти просмотры произошли в контексте плейлиста.
    • В разделе поддерживаемых показателей списка воспроизведения указаны агрегированные показатели видео и показатели списка воспроизведения, которые поддерживаются для отчетов по спискам воспроизведения.

  • Следующие новые показатели в плейлистах поддерживаются для отчетов по плейлистам для владельцев контента. Обратите внимание, что эти метрики поддерживаются только в том случае, если запрос API на получение отчетов не использует измерение isCurated . См. документацию по метрикам для определения каждой метрики:

  • Поведение метрики views теперь зависит от того, использовал ли запрос API, получивший отчет о плейлисте, измерение isCurated :

    • Если запрос включает параметр isCurated , показатель views — это показатель в списке воспроизведения, который указывает, сколько раз видео просматривалось в контексте плейлистов владельца контента.
    • Если запрос не включает измерение isCurated , показатель views представляет собой совокупный показатель видео, который определяет общее количество просмотров видео в плейлистах владельца контента, независимо от того, имели ли эти просмотры место в контексте плейлиста. В агрегированную сумму входят только просмотры видео, принадлежащие владельцу контента, связанному с каналом, которому принадлежит плейлист.

      В этих отчетах, в которых не используется параметр isCurated , метрика playlistViews указывает, сколько раз видео просматривалось в контексте плейлиста. Этот показатель учитывает просмотры всех видео в плейлисте, независимо от того, какому каналу они принадлежат.

  • Для каждого отчета о плейлисте документация по отчетам владельца контента теперь включает таблицы, показывающие поддерживаемые метрики для этого отчета в зависимости от того, включает ли запрос API измерение isCurated . Пример см. в разделе, посвященном определению отчетов по спискам воспроизведения на основе времени .

19 января 2024 г.

API YouTube Analytics (целевые запросы) имеет несколько обновлений, связанных с отчетами о плейлистах каналов. Обновления включают устаревший параметр и несколько новых и обновленных показателей:

  • Примечание. Это объявление об устаревании.

    Параметр isCurated устарел для отчетов по каналам. Он перестанет поддерживаться 30 июня 2024 г. или после этой даты. Определение этого параметра было соответствующим образом обновлено.

    Чтобы сохранить обратную совместимость при удалении измерения isCurated , вам также необходимо обновить код, чтобы получить метрику playlistViews вместо метрики views только для отчетов по спискам воспроизведения. Поскольку метрика views по-прежнему поддерживается для отчетов по спискам воспроизведения, хотя и с другим значением, API по-прежнему будет возвращать данные, если вы не обновите имя метрики. Конечно, вы можете изменить свое приложение для получения и отображения как views , так и playlistViews .

    Помимо измерения isCurated , в новых отчетах больше не поддерживаются следующие функции API:

    • Фильтры местоположения, такие как continent и subcontinent не поддерживаются для отчетов о новых плейлистах каналов.
    • Метрики redViews и estimatedRedMinutesWatched больше не поддерживаются для отчетов о плейлистах новых каналов. Эти метрики не были доступны в YouTube Studio, поэтому это изменение приводит функциональность API в соответствие с функциями, доступными в приложении Studio.
    • Измерения subscribedStatus и youtubeProduct больше не поддерживаются в качестве фильтров для отчетов о плейлистах канала. Эти фильтры были недоступны в YouTube Studio, поэтому это изменение приводит функциональность API в соответствие с функциональностью, доступной в приложении Studio.

  • Раздел отчетов о плейлистах документации по отчетам о каналах был обновлен, чтобы более подробно объяснить типы показателей, которые поддерживаются для отчетов о плейлистах:

    • Агрегированные показатели видео предоставляют показатели активности пользователей и показов, которые суммируются для всех видео в плейлистах канала, которые также принадлежат этому каналу. Агрегированные показатели видео поддерживаются только для запросов API, которые не используют измерение isCurated .
    • Показатели плейлиста отражают активность и вовлеченность пользователей в контексте страницы плейлиста. Эти показатели включают в себя данные о том, что будут также учитываться просмотры видео, не принадлежащих вам, в плейлисте, но только тогда, когда эти просмотры произошли в контексте плейлиста.
    • В разделе поддерживаемых показателей списка воспроизведения указаны агрегированные показатели видео и показатели списка воспроизведения, которые поддерживаются для отчетов по спискам воспроизведения.

  • В отчетах по плейлистам для каналов поддерживаются следующие новые показатели плейлистов . Эти показатели пока не поддерживаются для отчетов владельцев контента. Обратите внимание, что эти метрики поддерживаются только в том случае, если запрос API на получение отчетов не использует измерение isCurated . См. документацию по метрикам для определения каждой метрики:

  • Поведение метрики views теперь зависит от того, использовал ли запрос API, получивший отчет о плейлисте, измерение isCurated :

    • Если запрос включает параметр isCurated , показатель views — это показатель в плейлисте, который указывает, сколько раз видео было просмотрено в контексте плейлистов канала.
    • Если запрос не включает измерение isCurated , показатель views представляет собой совокупный показатель видео, который определяет общее количество просмотров видео в плейлистах канала, независимо от того, имели ли эти просмотры место в контексте плейлиста. В агрегированную сумму входят только просмотры видео, принадлежащих каналу, которому принадлежит плейлист.

      В этих отчетах, в которых не используется параметр isCurated , метрика playlistViews указывает, сколько раз видео просматривалось в контексте плейлиста. Этот показатель учитывает просмотры всех видео в плейлисте, независимо от того, какому каналу они принадлежат.

  • Для каждого отчета о плейлисте документация по отчетам о каналах теперь включает таблицы, показывающие поддерживаемые метрики для этого отчета в зависимости от того, включает ли запрос API измерение isCurated . Пример см. в разделе, посвященном определению отчетов по спискам воспроизведения на основе времени .

04 декабря 2023 г.

API YouTube Analytics (целевые запросы) был обновлен и теперь объединяет два значения измерения insightTrafficSourceType . Ранее этот параметр различал видео, воспроизводимые как часть списка воспроизведения ( PLAYLIST ), и просмотры, происходящие со страницы, на которой перечислены все видео в списке воспроизведения ( YT_PLAYLIST_PAGE ). В дальнейшем оба типа представлений будут связаны со значением измерения PLAYLIST .

15 декабря 2022 г.

API YouTube Analytics (целевые запросы) поддерживает два новых параметра и один новый отчет:

  • Новый отчет показывает активность пользователей по городам. Этот отчет доступен владельцам каналов и контента . Этот отчет содержит новый параметр city , который определяет оценку YouTube города, в котором имела место активность пользователя.

  • Новое измерение creatorContentType определяет тип контента YouTube, который связан с показателями активности пользователей в строке данных. Поддерживаемые значения: LIVE_STREAM , SHORTS , STORY и VIDEO_ON_DEMAND .

    Параметр creatorContentType поддерживается как необязательный параметр для всех видеоотчетов владельцев каналов и контента.

  • Руководство по примерам запросов API YouTube Analytics теперь включает примеры для обоих новых параметров.

  • Ссылки на измерения 7DayTotals и 30DayTotals были удалены из документации. Об прекращении поддержки этих размеров было объявлено в октябре 2019 года.

26 августа 2022 г.

API YouTube Analytics (целевые запросы) и API отчетов YouTube (массовые отчеты) поддерживают новое значение подробностей об источнике трафика:

  • В API YouTube Analytics API (целевые запросы), если значение измерения insightTrafficSourceType равно SUBSCRIBER , тогда для значения insightTrafficSourceDetail можно установить podcasts , что указывает на то, что трафик был перенаправлен с целевой страницы подкастов.
  • В API отчетов YouTube (массовые отчеты), если значение параметра traffic_source_type равно 3 , то значение traffic_source_detail может быть установлено в podcasts , что указывает на то, что трафик был перенаправлен с целевой страницы подкастов.

11 февраля 2022 г.

Набор допустимых значений для gender измерения изменится 11 августа 2022 года или после этой даты. Это может быть обратно несовместимым изменением в вашей реализации API. В соответствии с разделом «Изменения, несовместимые с обратной совместимостью» Условий обслуживания API-сервисов YouTube, об этом изменении объявляется за шесть месяцев до его вступления в силу. Обновите реализацию API до 11 августа 2022 г., чтобы обеспечить плавный переход к новому набору значений.

Конкретные изменения, которые вносятся:

  • В API YouTube Analytics (целевые запросы) gender параметр в настоящее время поддерживает два значения: female и male . 11 августа 2022 г. или позднее это измерение будет поддерживать три значения: female , male и user_specified .
  • В API отчетов YouTube (массовые отчеты) gender параметр в настоящее время поддерживает три значения: FEMALE , MALE и GENDER_OTHER . 11 августа 2022 г. или позже набор поддерживаемых значений изменится на FEMALE , MALE и USER_SPECIFIED .

9 февраля 2022 г.

По состоянию на 13 декабря 2021 года были обновлены два показателя, исключающие трафик зацикленных клипов. Это изменение затрагивает как API YouTube Analytics (целевые запросы), так и API отчетов YouTube (массовые отчеты).

2 февраля 2022 г.

Этот API отчетов YouTube (массовые отчеты) поддерживает новое значение параметра источника трафика, которое указывает, что просмотры возникли в результате прямых перенаправлений :

  • В API отчетов YouTube (массовые отчеты) параметр traffic_source_type поддерживает значение 28 .

Для этого типа источника трафика измерение traffic_source_detail указывает идентификатор канала, с которого был перенаправлен зритель.

23 сентября 2020 г.

Этот API YouTube Analytics (целевые запросы) и API отчетов YouTube (массовые отчеты) поддерживают новое значение параметра источника трафика, которое указывает, что зритель перешел, проведя по вертикали при просмотре YouTube Shorts:

  • В API YouTube Analytics API (целевые запросы) параметр insightTrafficSourceType поддерживает значение SHORTS .
  • В API отчетов YouTube (массовые отчеты) параметр traffic_source_type поддерживает значение 24 .

Параметр сведений об источнике трафика — insightTrafficSourceDetail в API YouTube Analytics или traffic_source_detail в API отчетов YouTube — не заполняется для этого нового типа источника трафика.

20 июля 2020 г.

Это обновление охватывает два изменения, которые влияют на API YouTube Analytics (целевые запросы):

  • Максимальный размер группы отчетов YouTube Analytics увеличился с 200 до 500 объектов.
  • Параметр filters метода reports.query определяет список фильтров, которые следует применять при получении данных YouTube Analytics. Параметр поддерживает возможность указать несколько значений для фильтров video , playlist и channel , а максимальное количество идентификаторов, которые можно указать для этих фильтров, увеличено с 200 до 500 идентификаторов.

13 февраля 2020 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics (целевые запросы) и API отчетов YouTube (массовые отчеты). Подробнее об этих изменениях можно узнать в Справочном центре YouTube .

В обоих API меняется набор возможных значений детализации источников трафика для уведомлений. В целевых запросах уведомления отображаются как insightTrafficSourceType=NOTIFICATION . В массовых отчетах уведомления обозначаются как traffic_source_type=17 .

Новые значения разделяют уведомления, связанные с загруженными видео и прямыми трансляциями, которые ранее считались uploaded , на две категории:

  • uploaded_push — просмотры происходят из push-уведомлений, отправленных подписчикам при загрузке видео.
  • uploaded_other — просмотры возникли из-за не-push-уведомлений, таких как уведомления по электронной почте или входящих сообщениях, отправленных подписчикам при загрузке видео.

Эти значения возвращаются для временного диапазона, начинающегося с 13 января 2020 г. (13 января 2020 г.).

Кроме того, напоминаем, что эти значения представляют собой не сами уведомления, а скорее источники трафика, которые привели к определенным просмотрам на YouTube. Например, если в строке отчета указаны views=3 , traffic_source_type=17 ( NOTIFICATION ) и traffic_source_detail=uploaded_push , строка указывает, что три просмотра были результатом того, что зрители нажимали на push-уведомления, отправленные при загрузке видео.

15 октября 2019 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics (целевые запросы):

  • Примечание. Это объявление об устаревании.

    YouTube прекращает поддержку измерений 7DayTotals и 30DayTotals . Вы по-прежнему можете получать данные с использованием этих измерений до 15 апреля 2020 года. Начиная с этой даты или позже, попытки получить отчеты с использованием измерения 7DayTotals или 30DayTotals вернут ошибку.

    Обратите внимание, что пользователи могут воспроизводить некоторые данные для этих измерений, делая запросы с использованием измерения day и агрегируя или получая данные за семи- или 30-дневные периоды. Например:

    • Количество просмотров за семидневный период можно рассчитать путем суммирования количества просмотров за каждый день этого периода.
    • ViewerPercentage за семидневный период можно рассчитать, умножив количество просмотров, произошедших каждый день, на viewerPercentage за этот день, чтобы получить количество зрителей, вошедших в систему при просмотре видео в тот день. Затем можно добавить количество вошедших в систему зрителей за весь период и разделить на общее количество просмотров за этот период, чтобы получить процент просмотра за весь период.
    • Количество уникальных зрителей за семидневный период подсчитать невозможно, поскольку один и тот же зритель может быть рассчитан как уникальный зритель в разные дни. Однако вы можете использовать измерение month вместо измерения 30DayTotals , чтобы экстраполировать данные о количестве уникальных зрителей за 30-дневный период. Обратите внимание, что измерение month относится к календарным месяцам, тогда как измерение 30DayTotals вычисляет 30-дневные периоды на основе указанной даты начала и окончания.

27 июня 2019 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics (целевые запросы):

  • Поскольку версия 1 API полностью устарела, документация была обновлена ​​и удалены ссылки на эту версию, включая уведомление об устаревании и руководство по переходу, объясняющее, как обновиться до версии 2.

1 ноября 2018 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics (целевые запросы):

  • Версия 1 API устарела. Если вы еще этого не сделали, обновите свои клиенты API, чтобы они использовали версию 2 API, как можно скорее, чтобы свести к минимуму перебои в обслуживании. Более подробную информацию см. в руководстве по миграции .

    Обратите внимание, что график прекращения поддержки первоначально был объявлен 26 апреля 2018 г.

17 сентября 2018 г.

Это обновление содержит следующие изменения, связанные с API YouTube Analytics (целевые запросы):

  • В новом разделе анонимизации данных в обзорном документе модели данных объясняется, что некоторые данные YouTube Analytics ограничены, если показатели не соответствуют определенному пороговому значению. Это может произойти в самых разных случаях. На практике это означает, что отчет может не содержать все (или некоторые) ваши данные, если:

    1. видео или канал имеет ограниченный трафик в течение определенного периода времени,

      или

    2. вы выбрали фильтр или параметр, например источник трафика или страну, значения которого не соответствуют определенному порогу.

    В новом разделе также обсуждаются типы данных, которые могут быть ограничены в отчетах YouTube Analytics.

  • Документы отчетов о каналах и отчетах владельцев контента были обновлены, чтобы отразить тот факт, что метрики redViews и estimatedRedMinutesWatched больше не поддерживаются для отчетов о местоположении воспроизведения, источнике трафика и типе устройства/операционной системе.

18 июня 2018 г.

Это обновление содержит следующие изменения в API YouTube Analytics (целевые запросы):

  • Изменились требования к области применения следующих методов:
    • Запросы к методу reports.query должны иметь доступ к области https://www.googleapis.com/auth/youtube.readonly .
    • Запросы к методу groupItems.list должны иметь доступ к:
      • область https://www.googleapis.com/auth/youtube
        или
      • область действия https://www.googleapis.com/auth/youtube.readonly
        и
        область https://www.googleapis.com/auth/yt-analytics.readonly

      Первый вариант использует одну область, которая является областью чтения и записи, а второй вариант использует две области только для чтения.

23 мая 2018 г.

Это обновление содержит следующие изменения в API YouTube Analytics (целевые запросы):

  • Обзор API содержит новый раздел «агрегированные показатели и удаленные элементы» , в котором объясняется, как ответы API обрабатывают данные, связанные с удаленными ресурсами, такими как видео, плейлисты или каналы.
  • Раздел рекомендаций по обзору API был обновлен, чтобы напомнить вам, что вы можете использовать API данных YouTube для получения дополнительных метаданных для ресурсов, указанных в ответах API YouTube Analytics. Как указано в Политике разработчика API-сервисов YouTube (разделы с III.E.4.b по III.E.4.d), клиенты API должны либо удалить, либо обновить метаданные сохраненных ресурсов из этого API через 30 дней.

22 мая 2018 г.

Это обновление содержит следующие изменения, связанные с API отчетов YouTube (массовые отчеты):

  • Следующие изменения вступят в силу в июле 2018 года. Новые политики применяются глобально ко всем отчетам и отчетным заданиям.

    • После изменения большинство отчетов API, включая отчеты о заполнении, будут доступны в течение 60 дней с момента их создания. Однако отчеты, содержащие исторические данные, будут доступны в течение 30 дней с момента их создания.

      До этого объявления все отчеты API были доступны в течение 180 дней с момента их создания. Чтобы внести ясность: когда это изменение политики вступит в силу, отчеты с историческими данными старше 30 дней также больше не будут доступны через API. Все остальные отчеты старше 60 дней также станут недоступны. Таким образом, в документации теперь указано, что отчеты, созданные до изменения политики, будут доступны в течение 180 дней.

    • После изменения, когда вы планируете задание по составлению отчетов, YouTube будет создавать отчеты, начиная с этого дня, и охватывать 30-дневный период, предшествовавший запланированному заданию. До изменения, когда вы планируете задание по составлению отчетов, YouTube будет создавать отчеты, охватывающие 180-дневный период до времени, когда задание было запланировано.

  • Раздел рекомендаций был обновлен и напоминает вам, что вы можете использовать API данных YouTube для получения дополнительных метаданных для ресурсов, указанных в отчетах. Как указано в Политике разработчика API-сервисов YouTube (разделы с III.E.4.b по III.E.4.d), клиенты API должны либо удалить, либо обновить метаданные сохраненных ресурсов из этого API через 30 дней.

  • Раздел «Характеристики отчета» был обновлен, чтобы отметить, что, даже если данные отчета не фильтруются, отчеты, содержащие данные за период времени, начиная с 1 июня 2018 года, не будут содержать никаких ссылок на ресурсы YouTube, которые были удалены по крайней мере за 30 дней до даты создания отчета.

  • Раздел исторических данных обзора API был обновлен, чтобы отметить, что при планировании нового задания по составлению отчетов исторические отчеты обычно публикуются в течение нескольких дней. Ранее в документации указывалось, что предоставление таких отчетов может занять до 30 дней.

  • Раздел данных обратной засыпки в обзоре API был обновлен, чтобы более четко определить данные обратной засыпки как набор данных, который заменяет ранее предоставленный набор.

26 апреля 2018 г.

Версия 2 API YouTube Analytics (целевые запросы) (v2) теперь общедоступна. В следующем списке указаны изменения продукта и документации, связанные с новой версией API:

  • API версии 2 практически идентичен API версии 1. Однако вам, вероятно, потребуется обновить свой код, чтобы отразить изменения, перечисленные ниже. Все эти изменения подробно описаны в новом руководстве по миграции .

    • Версия API изменилась с v1 на v2 .
    • Базовый URL-адрес для запросов API изменился с https://www.googleapis.com/youtube/analytics/v1 на https://youtubeanalytics.googleapis.com/v2 .
    • У некоторых параметров метода reports.query обновлены имена. В частности, имена параметров, содержащие дефисы, например end-date в API версии 1, используют верблюжий регистр ( endDate ), а не дефисы в API версии 2. Это изменение делает имена параметров единообразными во всем API, поскольку в методах API для создания групп и управления ими уже используется верблюжий регистр для имен параметров.
    • API версии 2 не поддерживает пакетные запросы, отправляемые на глобальную пакетную точку HTTP Google ( www.googleapis.com/batch ). Если вы отправляете пакетные запросы через API версии 2, вместо этого вам необходимо использовать конечную точку https://youtubeanalytics.googleapis.com/v2 .

    Кроме того, некоторые функции версии 1 не поддерживаются в API версии 2:

    • Метод reports.query больше не поддерживает параметры запроса alt , quotaUser и userIp .
    • API версии 2 не предоставляет конечную точку пакета, которая поддерживает пакеты, состоящие из запросов к различным API. (Однако пакет может состоять из запросов к различным методам одного и того же API.) Это прекращение поддержки не относится только к API YouTube Analytics, поскольку Google прекращает поддержку глобальной конечной точки пакета во всех своих API.
    • API версии 2 не поддерживает протокол JSON-RPC, который поддерживался в API версии 1. Опять же, это прекращение поддержки не относится только к API YouTube Analytics.

  • Примечание. Это объявление об устаревании.

    Версия 1 API (v1) устарела и будет поддерживаться до 31 октября 2018 г. После этой даты все запросы к API версии 1 перестанут работать. Поэтому обязательно обновите API версии 2 не позднее 31 октября 2018 года, чтобы избежать перебоев в доступе к данным YouTube Analytics через API.

21 февраля 2018 г.

Это обновление содержит следующие изменения в API YouTube Analytics (целевые запросы):

  • Демографические отчеты о зрителях, которые объединяют статистику просмотров на основе возрастной группы и пола зрителей, больше не поддерживают измерение youtubeProduct , которое идентифицирует сервис YouTube, в котором произошла активность пользователя.

18 января 2018 г.

Это обновление содержит следующие изменения:

  • API отчетов YouTube (массовые отчеты)

    • Измерение operating_system , которое идентифицирует программную систему устройства, на котором были просмотры, теперь поддерживает следующее значение:
      • 25 : КайОС

  • API YouTube Analytics (целевые запросы)

    • Измерение operatingSystem поддерживает значение измерения KAIOS .

20 декабря 2017 г.

Это обновление содержит два изменения, связанных с API отчетов YouTube:

  • Сервер API теперь поддерживает сжатие gzip для запросов на загрузку отчетов. Обратите внимание, что сжатие gzip не поддерживается для других типов запросов API. Включение сжатия gzip уменьшает пропускную способность, необходимую для каждого ответа API. И хотя вашему приложению потребуется дополнительное время ЦП для распаковки ответов API, выгода от потребления меньшего количества сетевых ресурсов обычно перевешивает эти затраты.

    Чтобы получить ответ в кодировке gzip, установите для заголовка HTTP-запроса Accept-Encoding значение gzip как показано в следующем примере:

    Accept-Encoding: gzip

    Эта функциональность объясняется в обзоре API и в определении свойства downloadUrl ресурса report .

  • Документация по параметрам age group и gender была исправлена, чтобы отображать фактические значения, которые API возвращает для этих параметров. Обратите внимание, что это исправление документации и не отражает изменение функциональности или поведения API. В частности, изменились следующие значения:

    • Значения измерения age_group используют прописные буквы, содержат символы подчеркивания между словом AGE и цифрами возрастной группы, а также символы подчеркивания вместо дефисов. Таким образом, такие значения, как age13-17 и age18-24 были исправлены на AGE_13_17 и AGE_18_24 соответственно.
    • В значениях gender измерения используются прописные буквы. Таким образом, значения female , male и gender_other были исправлены на FEMALE , MALE и GENDER_OTHER .

10 августа 2017 г.

10 августа 2016 г. в этой документации было объявлено о прекращении поддержки показателя earnings API YouTube Analytics. (В то же время в API добавлена ​​поддержка новой метрики с именем estimatedRevenue , которая предоставляет те же данные.)

Поскольку показатель earnings был основным показателем, он поддерживался в течение одного года с даты объявления. Теперь, когда этот период года закончился, однако, показатель earnings больше не поддерживается. В результате API запросы, которые указывают на метрику earnings теперь возвращают 400 HTTP -код ответа. Если вы еще не обновили свое приложение, чтобы использовать метрику estimatedRevenue вместо метрики earnings , пожалуйста, сделайте это как можно скорее.

Документация API была обновлена ​​для удаления оставшихся ссылок на метрику earnings .

6 июля 2017 года

Это обновление содержит следующие изменения:

  • YouTube Analytics API (целевые запросы)

    • Документация API была обновлена, чтобы отразить тот факт, что ответы API содержат данные вплоть до последнего дня в запрашиваемом диапазоне дат, для которого доступны все запрашиваемые показатели.

      Например, если запрос указывает дату окончания 5 июля 2017 года, а значения для всех запрошенных показателей доступны только до 3 июля 2017 года, которые станут последней датой, для которой данные включены в ответ. (Это верно, даже если данные для некоторых запрошенных метрик доступны за 4 июля 2017 года.)

    • Dimension adType теперь поддерживает значение reservedBumperInstream , которое относится к не поддающемуся видео объявлению до 6 секунд, которая играет до того, как можно будет просмотреть видео. Формат AD идентичен AD auctionBumperInstream , но этот тип относится к рекламе, продаваемым на зарезервированной, а не на аукционной основе.

  • Youtube Reporting API (объемные отчеты)

    • Размер ad_type теперь поддерживает значение 20 , которое относится к бамперной рекламе, продаваемой на зарезервированной основе. Бампер-реклама-это не поддающиеся видеообъявлениям до 6 секунд, которые воспроизводятся до того, как можно будет просмотреть видео. Обратите внимание, что значение 19 для этого измерения также относится к бамперской рекламе, которая продается на аукционе , а не за зарезервированной основой.

    • Отчеты о работах для следующих отчетов API отчетности YouTube были удалены:

      • 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

      Эти типы отчетов были объявлены как устаревшие 15 сентября 2016 года , и отчеты больше не были получены для этих типов отчетов после 15 декабря 2016 года. Ранее созданные отчеты все еще были доступны в течение 180 дней с момента их создания. Таким образом, некоторые отчеты были доступны уже 15 июня 2017 года. Однако, поскольку отчеты больше не доступны, рабочие места, связанные с отчетами, также не нужны.

24 мая 2017 года

Все рабочие места для отчетов для следующих отчетов API отчетности YouTube были удалены:

  • content_owner_ad_performance_a1
  • content_owner_asset_estimated_earnings_a1
  • content_owner_estimated_earnings_a1

Эти типы отчетов были объявлены как устаревшие 22 июня 2016 года , и отчеты больше не были получены для этих типов отчетов после 22 сентября 2016 года. Ранее генерируемые отчеты все еще были доступны в течение 180 дней с момента их создания. Таким образом, некоторые отчеты были доступны до 22 марта 2017 года. Однако, поскольку отчеты больше не доступны, рабочие места, связанные с отчетами, тоже не нужны.

22 мая 2017 года

Это обновление содержит следующие изменения:

  • Youtube Reporting API (объемные отчеты)

    • Размер sharing_service , который идентифицирует услугу, которая использовалась для обмена видео, теперь поддерживает следующие значения:

      • 85 : музыка на YouTube
      • 86 : игры на YouTube
      • 87 : дети на YouTube
      • 88 : телевизор YouTube

      Кроме того, имя, используемое для идентификации значения 52 было обновлено в документации Kakao (Kakao Talk), чтобы более четко отличить его от значения 73 (история Kakao). Это изменение не отражает каких -либо изменений в поведении API или классификации видео, которые делятся с этими услугами.

  • YouTube Analytics API (целевые запросы)

    • Размер sharingService теперь поддерживает следующие значения:

      • YOUTUBE_GAMING
      • YOUTUBE_KIDS
      • YOUTUBE_MUSIC
      • YOUTUBE_TV

28 марта 2017 г.

Владельцы каналов, которые могут получить доступ к данным о доходах через аналитику YouTube в Creator Studio, теперь также могут получить доступ к данным о доходах через API YouTube Analytics:

17 марта 2017 года

Это обновление содержит следующие изменения:

  • API API YouTube Analytics поддерживает redViews и estimatedRedMinutesWatched Metrics, оба из которых относятся к YouTube Red Viewershiew. Фактически, API фактически поддерживает эти метрики в течение некоторого времени, и API отчетности YouTube уже поддерживает обе метрики, как объявлено 15 сентября 2016 года .

    • Метрика redViews идентифицирует количество раз, когда видео -участники Red просмотрели видео.
    • Метрика estimatedRedMinutesWatched определяет количество минут, которые youtube Red смотрели видео.

    Отчеты о каналах и документации владельца контента были обновлены, чтобы показать, какие отчеты поддерживают два новых показателя. Они поддерживаются в любых отчетах, которые уже поддержали views и estimatedMinutesWatched счетов.

3 марта 2017 года

Это обновление содержит следующие изменения:

  • Youtube Reporting API (объемные отчеты)

    • Определение измерения date было исправлено, чтобы отметить, что значение измерения относится к периоду, начинающемуся в 12:00 в Тихоокеанском времени и заканчивается в 23:59 Тихоокеанское время в указанный день, месяц и год. В зависимости от времени года, Pacific Time является UTC-7 или UTC-8.

      Хотя даты обычно представляют 24-часовой период, даты, когда часы регулируются вперед, представляют 23-часовой период, а даты, когда часы регулируются назад, представляют 25-часовой период. (Ранее в документации говорилось, что каждая дата представляла собой уникальный 24-часовой период, и это время Тихого океана всегда было UTC-8.)

      Обратите внимание, что эта коррекция не представляет собой изменение фактического поведения API.

    • Измерение operating_system , которое идентифицирует программную систему устройства, на котором произошли представления, теперь поддерживает следующие значения:
      • 22 : Тизен
      • 23 : Firefox
      • 24 : Realmedia

    • Все задания отчетности для типа отчета content_owner_basic_a1 были удалены. Этот тип отчета был полностью устарел по состоянию на 19 августа 2016 года , но ранее сгенерированные отчеты content_owner_basic_a1 все еще были доступны в течение 180 дней с момента их создания. Таким образом, некоторые отчеты были доступны уже 19 февраля 2017 года. Однако, поскольку отчеты больше не доступны, рабочие места, связанные с отчетами, также не нужны.

  • YouTube Analytics API (целевые запросы)

    • Описание измерений, связанных с time periods было исправлено, чтобы отметить, что значение измерения относится к периоду, начинающемуся в 12:00 по тихоокеанскому времени и заканчивается в 23:59 Тихоокеанское время в указанный день, месяц и год. В зависимости от времени года, Pacific Time является UTC-7 или UTC-8.

      Хотя даты обычно представляют 24-часовой период, даты, когда часы регулируются вперед, представляют 23-часовой период, а даты, когда часы регулируются назад, представляют 25-часовой период. (Ранее в документации указывалось, что Тихоокеанское время было UTC-8 и не упоминала о возможности того, что день может не представлять 24-часовой период.)

      Обратите внимание, что эта коррекция не представляет собой изменение фактического поведения API.

    • Документация канала сообщается о том, что в настоящее время отчеты каналов в настоящее время не содержат доходов или показателей производительности рекламы. В результате https://www.googleapis.com/auth/yt-analytics-monetary.readonly Scope в настоящее время не предоставляет доступ к денежным данным в отчетах каналов.

    • Размер operatingSystem поддерживает три новых значения измерения:
      • FIREFOX
      • REALMEDIA
      • TIZEN

8 февраля 2017 года

API YouTube Analytics теперь поддерживает необязательный параметр include-historical-channel-data . Обратите внимание, что этот параметр актуален только при получении отчетов владельца контента .

Параметр позволяет владельцу контента указать, что ответ API должен включать в себя время наблюдения за каналами и просмотр данных с периода времени до того, как каналы были связаны с владельцем контента. Значение параметра по умолчанию является false , что означает, что по умолчанию ответ API включает в себя только время наблюдения и просмотр данных с момента, когда каналы были связаны с владельцем контента.

Эти правила также применяются, если запрос API получает данные для нескольких каналов:

  • Если значение параметра является false , то время наблюдения и представления данных, возвращаемых для любого данного канала, основано на дате, когда этот канал был связан с владельцем контента.

    Важно помнить, что разные каналы могли быть связаны с владельцем контента в разные даты. Если запрос API получает данные для нескольких каналов, а значение параметра является false , то ответ API содержит время наблюдения и просмотр данных на основе даты связывания для каждого соответствующего канала.
  • Если значение параметра true , то ответ возвращает время наблюдения и просмотр данных для всех каналов на основе дат начала и окончания, указанных в запросе API.

15 декабря 2016 года

Следующие отчеты API отчетности на YouTube больше не поддерживаются и были удалены из документации. Доступна более новая версия каждого отчета. ( Объявление об испаке этих отчетов было сделано 15 сентября 2016 года.)

Список текущих типов отчетов в справочной документации API также был обновлен.

11 ноября 2016 года

Это обновление содержит следующие изменения:

    API Reporting YouTube поддерживает три новых отчета о конечных экранах, а также новые размеры и показатели для этих отчетов. Отчеты предоставляют создание и проведенные статистики для конечных экранов, которые отображаются после того, как видео перестает играть.

    • Отчеты о конечном экране

      • Отчет о конечном экране для видео каналов содержит статистику для всех видео канала.
      • Отчет о конечном экране для видео с владельцем контента содержит статистику для видео на любом из каналов владельца контента.
      • Отчет о конечном экране для активов владельца контента содержит статистику для активов, связанных с видео, после чего отображаются конечные экраны.

    • Размеры конечного экрана

      • end_screen_element_type : тип элемента конечного экрана, связанный со статистикой.
      • end_screen_element_id : Идентификатор, который YouTube использует для однозначного идентификации элемента конечного экрана.

    • Метрики конечного экрана

      Примечание. Данные для метриков конечного экрана доступны по состоянию на 1 мая 2016 года.

      • end_screen_element_impressions : общее количество отпечатков элемента конечного экрана. Одно впечатление регистрируется для каждого элемента конечного экрана, который отображается.
      • end_screen_element_clicks : количество раз, когда элементы экрана нажимали.
      • end_screen_element_click_rate : скорость клика для элементов экрана.

      • Справочный центр YouTube содержит более подробную информацию о добавлении конечных экранов к вашим видео .

    • Следующие отчеты больше не поддерживаются и были удалены из документации. Доступна более новая версия каждого отчета. ( Объявление об испаке этих отчетов было сделано 22 июня 2016 года.)

    8 ноября 2016 года

    Это обновление содержит следующие изменения в API YouTube Analytics:

    • Метрики в следующем списке полностью устарели и больше не поддерживаются. Как было объявлено 10 августа 2016 года, новые метрики, относящиеся к тем же данным, уже поддерживаются. В таблице ниже показано устаревшее метрическое имя и новое метрическое имя:

      Устаревшая метрика Новая метрика
      adEarnings estimatedAdRevenue
      impressionBasedCpm cpm
      impressions adImpressions
      redPartnerRevenue estimatedRedPartnerRevenue

    27 октября 2016 года

    YouTube теперь автоматически генерирует набор отчетов по доходам от рекламы, управляемых системой, для владельцев контента, которые имеют доступ к соответствующим отчетам в разделе отчетов на YouTube Creator Studio. Новые отчеты API, управляемые системой, предназначены для предоставления программного доступа к данным, которые также доступны в отчетах вручную загружаемых Creator Studio.

    Обзор отчетов, управляемый системой, содержит краткий обзор новых отчетов и объясняет процесс для их извлечения через API. Этот процесс немного отличается от процесса для получения объемных отчетов для аналитики YouTube, поскольку партнерам не нужно планировать работы для создания отчетов.

    Свойство id ресурса reportType было обновлено, чтобы включить список отчетов, управляемых системой, которые вы можете получить через API:

    • Ежемесячный мировой доход от рекламы на видео
    • Ежедневно, доход от рекламы в страну за видео
    • Ежемесячный мировой доход от рекламы на активу
    • Ежедневно, доход от рекламы на расстояние от актива
    • Претензии (в этом отчете не содержатся данные о доходах)

    27 сентября 2016 года

    Примечание: это объявление об ископке.

    Метрика uniques Api YouTube Analytics установилась. Это не основная метрика, и она будет поддерживаться до 31 октября 2016 года.

    15 сентября 2016 года

    Это обновление содержит следующие изменения API отчетности YouTube:

    • API поддерживает два новых показателя, связанных с YouTube Red Viewershiewership:

      • red_views : количество раз, когда видео было просмотрено youtube Red Members.
      • red_watch_time_minutes : количество минут, которые YouTube Red смотрели видео.

    • API поддерживает новые версии из 20 отчетов. Все новые версии поддерживают новые метрики red_views и red_watch_time_minutes .

      Для каждого отчета число в новом идентификаторе типа отчета на один номер выше, чем в старом идентификаторе типа отчета. (Старые версии этих отчетов в настоящее время устанавливаются, как описано позже в этой истории пересмотра.) Например, отчет channel_basic_ a1 теперь устарел и был заменен отчетом channel_basic_ a2 .

      Следующие списки определяют новые идентификаторы типа отчета:

    • Примечание: это объявление об ископке.

      Обратите внимание, что если у вас уже есть задания, чтобы создать любую из более старых версий отчетов, перечисленных выше, вам необходимо создать новые рабочие места для переименованных отчетов. В сочетании с выпуском новых версий отчета были устарели следующие версии отчета:

      • 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

      Если у вас есть рабочие места для любого из этих отчетов, вы не должны ожидать, что YouTube будет генерировать новые отчеты для этих рабочих мест после 15 декабря 2016 года. Сформированные отчеты все еще будут доступны в течение 180 дней с момента их сведения.

    19 августа 2016 г.

    Это обновление содержит следующее изменение API отчетности YouTube:

    • Отчет content_owner_basic_a1 был полностью устарел и удален из документации. YouTube больше не будет генерировать новые отчеты такого типа, хотя уже сгенерированные отчеты все равно будут доступны в течение 180 дней с момента их сведения.

      Замена отчета content_owner_basic_a1 - это отчет content_owner_basic_a2 , как объяснено в записи истории пересмотра за 19 мая 2016 года .

    11 августа 2016 года

    Это обновление содержит следующие изменения:

    • Недавно опубликованные Услуги службы услуг API YouTube («Обновленные термины»), подробно обсуждаемые в блоге YouTube Engineering and Developers , предоставляет богатый набор обновлений в текущих условиях обслуживания. В дополнение к обновленным условиям , которые вступит в силу по состоянию на 10 февраля 2017 года, это обновление включает в себя несколько подтверждающих документов, которые помогут объяснить политику, за которыми должны следовать разработчики.

      Полный набор новых документов описан в истории пересмотра для обновленных терминов . Кроме того, будущие изменения в обновленных терминах или в тех подтверждающих документах также будут объяснены в этой истории пересмотра. Вы можете подписаться на изменения списка каналов RSS в этой истории пересмотра по ссылке в этом документе.

    10 августа 2016 года

    Это обновление включает в себя следующие изменения:

    • YouTube Analytics API (целевые запросы)

      • Примечание: это объявление об ископке.

        Метрики в следующей таблице устанавливаются. В то же время вводятся новые метрики, относящиеся к тем же данным. По сути, это означает, что старые метрики переименованы в переименование, хотя API YouTube Analytics будет поддерживать оба метрических имена до тех пор, пока даты снижения, указанные в таблице.

        Старое метрическое название Новое метрическое название Дата поддержки
        earnings estimatedRevenue 10 августа 2017 г.
        adEarnings estimatedAdRevenue 4 ноября 2016 года
        redPartnerRevenue estimatedRedPartnerRevenue 4 ноября 2016 года
        impressionBasedCpm cpm 4 ноября 2016 года
        impressions adImpressions 4 ноября 2016 года

        Обратите внимание, что показатель earnings был основным показателем , поэтому он будет поддерживаться в течение одного года с даты этого объявления. Другие показатели, которые не были основными показателями, будут поддерживаться в течение трех месяцев до 4 ноября 2016 года.

        Например, до 4 ноября 2016 года запрос API может указать метрику impressionBasedCpm , метрику cpm или оба. Однако после этой даты будет поддержан только показатель cpm .

      • insightTrafficSourceType Dimension поддерживает два новых значения измерения:
        • CAMPAIGN_CARD : Этот источник трафика поддерживается только для отчетов владельца контента . Это указывает на то, что представления возникают из заявленных пользовательских видеороликов, которые владелец контента использовал для продвижения просмотренного контента.
        • END_SCREEN : Данные относятся к представлениям, которые происходили из конечного экрана другого видео.

        Для обоих новых источников трафика вы также можете получить отчет traffic source detail . В обоих случаях измерение insightTrafficSourceDetail идентифицирует видео, из которого был направлен зритель.

      • Dimension теперь поддерживает Value adType , который относится к не подлежащему видеообъявлению до 6 секунд, которая играет до того auctionBumperInstream как можно просмотреть видео.

    • Youtube Reporting API (объемные отчеты)

      • Размер traffic_source_type теперь поддерживает следующие значения:
        • 19 : Этот источник трафика поддерживается только для отчетов владельца контента . Это указывает на то, что представления возникают из заявленных пользовательских видеороликов, которые владелец контента использовал для продвижения просмотренного контента.
        • 20 : Данные относятся к представлениям, которые возникли из конечного экрана другого видео.

        Для обоих новых источников трафика измерение traffic_source_detail идентифицирует видео, из которого был направлен зритель.

      • Список основных метрик API был исправлен, чтобы перечислить estimated_partner_revenue как основной метрику и удалить earnings из этого списка. (Метрика earnings никогда не поддерживалась в API отчетности YouTube.)

      • Размер ad_type теперь поддерживает значение 19 , которое ссылается на бамперскую рекламу, которая представляет собой не поддающуюся видеообъявления до 6 секунд, которые воспроизводятся до того, как можно будет просмотреть видео.

    18 июля 2016 года

    Это обновление включает в себя следующие изменения:

    • YouTube Analytics API (целевые запросы)

      • Списки поддерживаемых метрик для следующих отчетов о каналах были обновлены, чтобы включить показатели карт. Поддержка показателей карт в этих отчетах была фактически добавлена ​​28 июня 2016 года, и запись истории пересмотра за эту дату более подробно объясняет изменение. Отчеты:
        • Основная активность пользователя для штатов США
        • Активность пользователя в штатах США в течение определенных периодов времени
        • Активность пользователя по провинции
        • Активность пользователя подписанным статусом
        • Активность пользователя подписанным статусом для провинций
        • Лучшие видео по штату
        • Лучшие видео для подписанных или отписанных зрителей

      • Списки фильтров были исправлены как для отчетов о хранении аудитории канала , так и для отчетов по удержанию аудитории контента, чтобы отразить, что необходим video , и group фильтр не поддерживается.

        Ранее документация для обоих отчетов неправильно указывалась, что отчет может быть извлечен с использованием одного из этих двух фильтров или не использует ни фильтра.

    • Youtube Reporting API (объемные отчеты)

      • В обзоре API в разделе, в котором объясняется, как получить URL -адрес загрузки отчета, был исправлен, чтобы заявить, что YouTube генерирует загружаемые отчеты в течение нескольких дней, на которые не было доступно данные. Эти отчеты содержат строку заголовка, но не содержат дополнительных данных. Эта информация уже была обновлена ​​в разделе характеристик отчета того же документа 12 апреля 2016 года .
      • Список измерений в отчете content_owner_asset_cards_a1 был исправлен, чтобы отразить, что в отчете используется измерение card_id . Ранее документация неправильно перечислила имя измерения как card_title .

    28 июня 2016 года

    Документация по API youtube Analytics была обновлена, чтобы отразить поддержку показателей карт в многочисленных отчетах о каналах и владельцах контента . Недавно поддерживаемые метрики:

    Метрики поддерживаются в следующих типах отчетов:

    22 июня 2016 г.

    Это обновление содержит следующие изменения API отчетности YouTube. Первое изменение относится к API в целом, а оставшиеся изменения влияют только на отчеты владельца контента :

    • Раздел характеристик отчета обзора API был обновлен, чтобы уточнить, что отчеты доступны через API в течение 180 дней с момента, когда они генерируются.

      Ранее в документации говорилось, что отчеты доступны в течение периода до 180 дней до даты отправки запроса API. Хотя это и технически верно, оригинальный текст, в лучшем случае, довольно запутанным.

    • API поддерживает новые версии трех отчетов. Два из этих отчетов также содержат новые и переименованные метрики:

      • Отчет content_owner_ad_rates_a1 - это новая версия отчета content_owner_ad_performance_a1 . Недавно переименованный отчет идентичен предыдущей версии.

      • Два отчета, в которых есть новые версии, были переименованы в переименование:

        • Новая версия отчета content_owner_estimated_earnings_a1 называется content_owner_estimated_revenue_a1 .
        • Новая версия отчета content_owner_asset_estimated_earnings_a1 называется content_owner_asset_estimated_revenue_a1 .

        Оба недавно переименованных отчета отличаются от своих предшественников следующими способами:

        • Они добавляют новую метрику estimated_partner_red_revenue , которая оценивает общую прибыль от подписки на YouTube Red.
        • Они добавляют новую метрику estimated_partner_transaction_revenue , которая оценивает доход от транзакций, таких как платный контент и финансирование поклонников, за исключением любых возмещений, заряженных партнером.
        • Они переименованы в метрику estimated_partner_ad_sense_revenue до out estimated_partner_ad_auction_revenue .
        • Они переименованы в метрику estimated_partner_double_click_revenue до out out estimated_partner_ad_reserved_revenue .

      Обратите внимание, что если у вас уже есть работа, чтобы создать любую из более старых версий этих отчетов, вам необходимо создать новые рабочие места для переименованных отчетов. В сочетании с выпуском новых версий отчета, content_owner_ad_performance_a1 , content_owner_estimated_earnings_a1 и content_owner_asset_estimated_earnings_a1 установили отчеты.

      Если у вас есть рабочие места для любого из этих отчетов, вы не должны ожидать, что YouTube будет создавать новые отчеты для этих рабочих мест после 22 сентября 2016 года. Сформированные отчеты все еще будут доступны в течение 180 дней с момента их сведения.

    • Определение свойства id ресурса reportType было обновлено, чтобы отразить текущий набор доступных отчетов.

    • Имена двух метрик были исправлены в документации, чтобы соответствовать именам, которые появляются в отчетах. Это исключительно исправление документации и не отражает изменение фактического содержимого отчета:

      • estimated_partner_ad_sense_revenue метрики estimated_partner_adsense_revenue Обратите внимание, однако, что этот показатель появляется только в двух отчетах, которые устарели с этим обновлением. Как описано выше, этот показатель был переименован в estimated_partner_ad_auction_revenue в новых версиях этих отчетов.
      • Имя метрики estimated_partner_doubleclick_revenue было обновлено до out out estimated_partner_double_click_revenue . Опять же, обратите внимание, что этот показатель появляется только в двух отчетах, которые устарели с этим обновлением. Как описано выше, этот показатель был переименован в estimated_partner_ad_reserved_revenue в новых версиях этих отчетов.

    • Документация Dimensions для API отчетности была обновлена, чтобы больше не перечислить свойства elapsed_video_time_percentage и audience_retention_type . Эти размеры в настоящее время не поддерживаются какими -либо отчетами, доступными через API.

    19 мая 2016 года

    Это обновление содержит следующие изменения API отчетности YouTube:

    • API поддерживает новую версию отчета об активности пользователя для владельцев контента . Идентификатор типа отчета для нового отчета - content_owner_basic_a2 . В отличие от предыдущей версии отчета, content_owner_basic_a1 , новая версия поддерживает likes и dislikes метрики.

      Если у вас уже есть задание по созданию отчета content_owner_basic_a1 , вам все равно нужно создать новое задание для отчета content_owner_basic_a2 . YouTube не автоматически переносит владельцев контента в новую версию отчета или автоматически создает задание для создания новой версии отчета. В некоторых реализациях появление новой, неожиданной работы может стать нарушением.

      В сочетании с выпуском нового отчета был устарел отчет content_owner_basic_a1 . Если у вас есть работа для этого отчета, вы не должны ожидать, что YouTube будет генерировать новые отчеты для этой работы после 19 августа 2016 года. Сформированные отчеты все еще будут доступны в течение 180 дней с момента их создания.

    • reportType , job и report ресурсов все поддерживают новое свойство, которое определяет, представляет ли связанный ресурс устаревший тип отчета:

      • Собственность reportType Resource deprecateTime определяет дату и время, когда тип отчета будет устарел. Это свойство имеет значение только для отчетов, которые были объявлены как устаревшие, а значение представляет дату, когда YouTube перестанет генерировать отчеты такого типа.

        После того, как тип отчета объявлен как устаревший, YouTube генерирует отчеты такого типа еще на три месяца. Например, это обновление 19 мая 2016 года объявляет о том, как отчет content_owner_basic_a1 . Таким образом, deprecateTime для этого типа отчета указывается время 19 августа 2016 года, после чего YouTube перестанет генерировать отчеты такого типа.

      • Собственность expireTime job ресурса определяет дату и время, когда работа истекает или истечет. Это свойство имеет ценность, если тип отчета, связанный с заданием, устарел или если отчеты, полученные для работы, не были загружены в течение длительного периода времени. Дата отмечает время, после чего YouTube больше не генерирует новые отчеты для работы.

      • Собственность jobExpireTime от report о том, как и срок действия работы, связанная с отчетом, истек срок действия истечения срока действия. Это свойство содержит то же значение, что и свойство expireTime в job ресурсе, как описано в предыдущем элементе в этом списке.

    • Метод jobs.create теперь возвращает 400 HTTP -код ответа ( Bad Request ), если вы попытаетесь создать задание для устаревшего отчета. Кроме того, в документации метода в настоящее время перечислены несколько других причин, которые приводят к сбою запроса API.

    12 апреля 2016 года

    Это обновление содержит следующие изменения, все это только влияет на API отчетности YouTube:

    • YouTube теперь генерирует данные, охватывающие 180-дневный период до того времени, когда работа отчетности была первой запланированной. Ранее, отчетный API не предоставил никаких исторических данных. Это изменение влияет на все рабочие места, в том числе те, которые созданы до этого объявления.

      Исторические отчеты публикуются, как только они будут доступны, хотя требуется примерно один месяц, чтобы все исторические данные были размещены на работу. Итак, через месяц после планирования работы отчетности у вас будет доступ к примерно семи месяцам данных. (Все исторические данные для рабочих мест, созданные до этого объявления, должны быть опубликованы в течение месяца после объявления.)

      Обратите внимание, что исторические данные доступны только с 1 июля 2015 года. В результате работы, созданные до 28 декабря 2015 года, будут иметь менее 180 дней исторических данных.

      Все эти изменения объясняются в новом разделе «Исторические данные обзора API».

    • Раздел характеристик отчета в API отчетности YouTube был обновлен с помощью следующих изменений:

      • В документации теперь говорится, что отчеты доступны в течение 180 дней после того, как они генерируются и, следовательно, доступны для клиентов API для загрузки. Ранее в документации говорилось, что отчеты были доступны в течение периода до шести месяцев до даты отправки запроса API.

      • Документация была обновлена, чтобы отразить тот факт, что API теперь генерирует загружаемые отчеты в течение нескольких дней, в которые не было доступно никаких данных. Эти отчеты будут содержать строки заголовков, но не будут содержать дополнительные данные.

    • API отчетности YouTube вскоре поддержит набор автоматически сгенерированных, управляемых системными отчетами, которые содержат данные о доходах от AD или данные о доходах от подписки на YouTube. Отчеты будут доступны для владельцев контента, которые уже могут получить доступ к отчетам о загружаемых доходах вручную в студии YouTube Creator . Таким образом, новая функция API обеспечит программный доступ к этим данным.

      Следующие изменения API теперь объявляются в подготовке к запуску отчетов, управляемых системой:

      • Новое свойство systemManaged job ресурса указывает, описывает ли ресурс работу, которая генерирует отчеты, управляемые системой. YouTube автоматически генерирует отчеты, управляемые системой для владельцев контента YouTube, а владельцы контента не могут модифицировать или удалять задания, которые создают эти отчеты.

      • Новый метод jobs.list включает параметр includeSystemManaged указывает, должен ли ответ API включать задания для отчетов, управляемых системой. Значение по умолчанию параметра false .

      • Новый параметр метода jobs.reports.list Method указывает на то, что ответ API должен содержать отчеты только в том случае startTimeAtOrAfter если самые ранние данные в отчете находятся в указанной дате или после. 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.

    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:

      Содержание
      Размеры:
      Необходимый deviceType
      Use 0 or more day , liveOrOnDemand , subscribedStatus , youtubeProduct
      Metrics:
      Use 1 or more views , estimatedMinutesWatched
      Filters:
      Use 0 or 1 country , province , continent , subContinent
      Use 0 or 1 video , group
      Use 0 or more operatingSystem , liveOrOnDemand , subscribedStatus , youtubeProduct

      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 am Pacific time (UTC-8). Previously, the documentation stated that the date began at 12:00 am (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 am 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:

    • The API documentation has been restructured in an effor to make the API easier to understand. As such, these changes do not describe new features:

      • The documentation now contains one page that lists all available channel reports and another that lists all available content owner reports . Previously, the documentation had separate pages for channel video reports, channel playlist reports, and so forth.

      • The new data model overview seeks to provide a clearer introduction to how the API works. Specifically, this document tries to better explain how YouTube uses metrics, dimensions, and filters to calculate report values.

      • The API's reports.query method, which you use to retrieve reports, is now documented separately. The information on that page had previously been on some other pages. The new page is designed to help you more easily identify the information you need to send to retrieve a report.

    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:

    • The API no longer supports the show dimension.

    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
      • Социальные
      • 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 US states and Washington DC : This report retrieves a province-by-province breakdown of view counts and other statistics for a channel's videos. The data covers US states and Washington DC 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
      • Социальные
      • 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 US 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:

    • 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:

    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.

    ,

    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 . Подписаться

    26 марта 2025 г.

    This update contains the following change related to the YouTube Analytics and Reporting APIs:

    Starting March 31, 2025, YouTube will change how views for Shorts are counted. In the past, for Shorts, a view was counted after a Short was played for a certain number of seconds. Now, views will count the number of times your Short starts to play or replay, with no minimum watch time requirement. Узнать больше

    The YouTube Analytics (Targeted Queries) and Reporting (Bulk Reports) APIs will be updated with the following changes:

    • For Shorts, views count the number of times a Short starts to play or replay.
    • A new metric, engagedViews , will be made available and will reflect the previous view-counting methodology.
    • If you own a channel or you are authorized to access data for a channel, you will be able to query both the updated views and engaged views.

    Targeted Queries will be updated by April 30th, and Bulk Reports will be updated by June 30th. Until then, views will be based on the old methodology. Shorts and channel views will not match with Analytics in Studio.

    Additionally, the previously-announced deprecation of the Daily Claims (Version 1.0) report has been delayed.

    Check this revision history to learn when changes are made to the APIs.

    March 3, 2025

    This update contains the following change related to the YouTube Reporting API:

    Note: This is a deprecation announcement.

    The Daily Claims (Version 1.0) report has been deprecated for partners. It will no longer be supported on or after April 30, 2025. The definition of that report has been updated accordingly. Use the latest Daily Claims report instead.

    November 15, 2024

    Note: The following change is effective as of November 18, 2024.

    The YouTube Analytics (Targeted Queries) API documentation has been updated to note that for Traffic Source reports , the API's reports.query method now returns an error if the product of # of queried videos X # of days in date range exceeds 50,000. For example, a query that retrieves data for 500 video IDs can request data for a maximum of 100 days.

    This change affects reports for both channels and content owners .

    To reduce the number of rows that a request returns, split your query into multiple queries that specify fewer videos or set shorter date ranges. As a rule, bulk reports are recommended for large data sets.

    6 мая 2024 г.

    The YouTube Analytics (Targeted Queries) API supports three new reports for channels:

    In addition, the Audience Retention report has been enhanced to support three new metrics:

    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.

    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.

    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 .

    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. Например:

      • 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:

      1. a video or channel has limited traffic during a specified time period,

        или

      2. 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:
      • Requests to the reports.query method must have access to the https://www.googleapis.com/auth/youtube.readonly scope.
      • Requests to the groupItems.list method must have access to either:
        • the https://www.googleapis.com/auth/youtube scope
          или
        • the https://www.googleapis.com/auth/youtube.readonly scope
          и
          the https://www.googleapis.com/auth/yt-analytics.readonly scope

        The first option uses one scope, which happens to be a read-write scope, while the second option uses two read-only scopes.

    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.

    18 января 2018 г.

    This update contains the following changes:

    • YouTube Reporting API (Bulk Reports)

      • The operating_system dimension, which identifies the software system of the device on which views occurred, now supports the following value:
        • 25 : KaiOS

    • YouTube Analytics API (Targeted Queries)

    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 .

    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:

    • YouTube Analytics API (Targeted Queries)

      • The API documentation has been updated to reflect the fact that API responses contain data up until the last day in the requested date range for which all metrics being queried are available.

        For example, if a request specifies an end date of July 5, 2017, and values for all of the requested metrics are only available through July 3, 2017, that will be the last date for which data is included in the response. (That is true even if data for some of the requested metrics is available for July 4, 2017.)

      • The adType dimension now supports the value reservedBumperInstream , which refers to a non-skippable video ad of up to 6 seconds that plays before a video can be viewed. The ad format is identical to the auctionBumperInstream ad, but this type refers to ads sold on a reserved rather than an auction basis.

    • YouTube Reporting API (Bulk Reports)

      • The ad_type dimension now supports the value 20 , which refers to bumper ads sold on a reserved basis. Bumper ads are non-skippable video ads of up to 6 seconds that play before a video can be viewed. Note that the value 19 for this dimension also refers to bumper ads that are sold on an auction rather than a reserved basis.

      • Reporting jobs for the following YouTube Reporting API reports have been deleted:

        • 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

        These report types were announced as deprecated on September 15, 2016 , and reports were no longer generated for those report types after December 15, 2016. Previously generated reports were still available for 180 days from the time they were generated. Thus, some reports were accessible as late as June 15, 2017. However, since the reports are no longer available, the jobs associated with the reports are not needed either.

    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:

    • YouTube Reporting API (Bulk Reports)

      • The sharing_service dimension, which identifies the service that was used to share videos, now supports the following values:

        • 85 : YouTube Music
        • 86 : YouTube Gaming
        • 87 : YouTube Kids
        • 88 : YouTube TV

        In addition, the name used to identify value 52 has been updated in the documentation to Kakao (Kakao Talk) to more clearly differentiate it from value 73 (Kakao Story). This change does not reflect any change in API behavior or classification of videos shared with these services.

    • YouTube Analytics API (Targeted Queries)

      • The sharingService dimension now supports the following values:

        • YOUTUBE_GAMING
        • YOUTUBE_KIDS
        • YOUTUBE_MUSIC
        • YOUTUBE_TV

    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:

    March 17, 2017

    This update contains the following changes:

    March 3, 2017

    This update contains the following changes:

    • YouTube Reporting API (Bulk Reports)

      • The definition of the date dimension has been corrected to note that the dimension value refers to the period beginning at 12:00 am Pacific time and ending at 11:59 pm Pacific time on the specified day, month, and year. Depending on the time of year, Pacific time is either UTC-7 or UTC-8.

        Though dates typically represent a 24-hour period, dates when clocks are adjusted forward represent a 23-hour period, and dates when clocks are adjusted backward represent a 25-hour period. (Previously, the documentation stated that each date represented a unique 24-hour period and that Pacific time was always UTC-8.)

        Note that this correction does not represent a change in actual API behavior.

      • The operating_system dimension, which identifies the software system of the device on which views occurred, now supports the following values:
        • 22 : Tizen
        • 23 : Firefox
        • 24 : RealMedia

      • All reporting jobs for the content_owner_basic_a1 report type have been deleted. That report type had been fully deprecated as of August 19, 2016 , but previously generated content_owner_basic_a1 reports were still available for 180 days from the time they were generated. Thus, some reports were accessible as late as February 19, 2017. However, since the reports are no longer available, the jobs associated with the reports are not needed either.

    • YouTube Analytics API (Targeted Queries)

      • The description of dimensions related to time periods has been corrected to note that the dimension value refers to the period beginning at 12:00 am Pacific time and ending at 11:59 pm Pacific time on the specified day, month, and year. Depending on the time of year, Pacific time is either UTC-7 or UTC-8.

        Though dates typically represent a 24-hour period, dates when clocks are adjusted forward represent a 23-hour period, and dates when clocks are adjusted backward represent a 25-hour period. (Previously, the documentation stated that Pacific time was UTC-8 and did not mention the possibility that a day might not represent a 24-hour period.)

        Note that this correction does not represent a change in actual API behavior.

      • The channel reports documentation has been updated to note that channel reports do not currently contain earnings or ad performance metrics. As a result, the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope does not currently grant access to monetary data in channel reports.

      • The operatingSystem dimension supports three new dimension values:
        • FIREFOX
        • REALMEDIA
        • TIZEN

    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.)

    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.

      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:

        Deprecated metric New metric
        adEarnings estimatedAdRevenue
        impressionBasedCpm cpm
        impressions adImpressions
        redPartnerRevenue estimatedRedPartnerRevenue

      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:

      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:

      • YouTube Analytics API (Targeted Queries)

        • Note: This is a deprecation announcement.

          The metrics in the following table are being deprecated. At the same time, new metrics referring to the same data are being introduced. In effect, this means that the old metrics are being renamed, though the YouTube Analytics API will support both metric names until the deprecation dates listed in the table.

          Old metric name New metric name Support date
          earnings estimatedRevenue 10 августа 2017 г.
          adEarnings estimatedAdRevenue November 4, 2016
          redPartnerRevenue estimatedRedPartnerRevenue November 4, 2016
          impressionBasedCpm cpm November 4, 2016
          impressions adImpressions November 4, 2016

          Note that the earnings metric was a core metric , so it will be supported for one year from the date of this announcement. The other metrics, which were not core metrics, will be supported for three months, until November 4, 2016.

          For example, until November 4, 2016, an API request can specify the impressionBasedCpm metric, the cpm metric, or both. However, after that date, only the cpm metric will be supported.

        • The insightTrafficSourceType dimension supports two new dimension values:
          • CAMPAIGN_CARD : This traffic source is only supported for content owner reports . It indicates that the views originated from claimed, user-uploaded videos that the content owner used to promote the viewed content.
          • END_SCREEN : The data pertains to views that originated from the endscreen of another video.

          For both new traffic sources, you can also retrieve a traffic source detail report. In both cases, the insightTrafficSourceDetail dimension identifies the video from which the viewer was referred.

        • The adType dimension now supports the value auctionBumperInstream , which refers to a non-skippable video ad of up to 6 seconds that plays before a video can be viewed.

      • YouTube Reporting API (Bulk Reports)

        • The traffic_source_type dimension now supports the following values:
          • 19 : This traffic source is only supported for content owner reports . It indicates that the views originated from claimed, user-uploaded videos that the content owner used to promote the viewed content.
          • 20 : The data pertains to views that originated from the endscreen of another video.

          For both new traffic sources, the traffic_source_detail dimension identifies the video from which the viewer was referred.

        • The API's list of core metrics has been corrected to list estimated_partner_revenue as a core metric and to remove the earnings from that list. (The earnings metric has never been supported in the YouTube Reporting API.)

        • The ad_type dimension now supports the value 19 that refers to bumper ads, which are non-skippable video ads of up to 6 seconds that play before a video can be viewed.

      July 18, 2016

      This update includes the following changes:

      • YouTube Analytics API (Targeted Queries)

        • The lists of supported metrics for the following channel reports have been updated to include card metrics. Support for card metrics in these reports was actually added on June 28, 2016, and the revision history entry for that date explains the change in more detail. The reports are:
          • Basic user activity for US states
          • User activity in US states for specific time periods
          • User activity by province
          • User activity by subscribed status
          • User activity by subscribed status for provinces
          • Top videos by state
          • Top videos for subscribed or unsubscribed viewers

        • The lists of filters have been corrected for both channel audience retention reports and content owner audience retention reports to reflect that the video filter is required and the group filter is not supported.

          Previously, the documentation for both reports incorrectly stated that the report could be retrieved using one of those two filters or using neither filter.

      • YouTube Reporting API (Bulk Reports)

        • In the API overview , the section that explains how to retrieve a report's download URL has been corrected to state that YouTube does generate downloadable reports for days on which no data was available. Those reports contain a header row but do not contain additional data. This information had already been updated in the Report characteristics section of the same document on April 12, 2016 .
        • The list of dimensions in the content_owner_asset_cards_a1 report has been corrected to reflect that the report uses the card_id dimension. Previously, the documentation incorrectly listed the dimension name as card_title .

      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.

      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:

        Содержание
        Размеры:
        Необходимый deviceType
        Use 0 or more day , liveOrOnDemand , subscribedStatus , youtubeProduct
        Metrics:
        Use 1 or more views , estimatedMinutesWatched
        Filters:
        Use 0 or 1 country , province , continent , subContinent
        Use 0 or 1 video , group
        Use 0 or more operatingSystem , liveOrOnDemand , subscribedStatus , youtubeProduct

        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 am Pacific time (UTC-8). Previously, the documentation stated that the date began at 12:00 am (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 am 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:

      • The API documentation has been restructured in an effor to make the API easier to understand. As such, these changes do not describe new features:

        • The documentation now contains one page that lists all available channel reports and another that lists all available content owner reports . Previously, the documentation had separate pages for channel video reports, channel playlist reports, and so forth.

        • The new data model overview seeks to provide a clearer introduction to how the API works. Specifically, this document tries to better explain how YouTube uses metrics, dimensions, and filters to calculate report values.

        • The API's reports.query method, which you use to retrieve reports, is now documented separately. The information on that page had previously been on some other pages. The new page is designed to help you more easily identify the information you need to send to retrieve a report.

      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:

      • The API no longer supports the show dimension.

      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
        • Социальные
        • 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 US states and Washington DC : This report retrieves a province-by-province breakdown of view counts and other statistics for a channel's videos. The data covers US states and Washington DC 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
        • Социальные
        • 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 US 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:

      • 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:

      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.