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

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

22 сентября 2025 г.

Ранее объявленное прекращение поддержки отчетов было отложено с 30 сентября 2025 г. на 31 октября 2025 г. Предыдущие версии отчетов, обновленные с учетом изменений в количестве просмотров Shorts, будут по-прежнему доступны до этого времени, за исключением отчета по заявкам v1.0 ( content_owner_active_claims_a1 ) и отчета по заявкам v1.1 ( content_owner_active_claims_a2 ), которые по-прежнему будут считаться устаревшими 30 сентября.

24 июня 2025 г.

Как было объявлено 26 марта 2025 года , API массовых отчётов будет обновлён в связи с изменением количества просмотров коротких видео. Были внесены следующие изменения:

• Для каждого отчёта, включающего представления (а таких отчётов большинство), были созданы новые версии. Номер версии каждого затронутого отчёта увеличился на единицу, например, с версии a2 до версии a3 .
• Для коротких видео просмотры теперь будут учитываться по количеству запусков или повторов короткого видео. Для видео изменений нет.
• Обновленные отчеты будут включать новый столбец engaged_views , который будет отражать предыдущую методологию подсчета просмотров.

Эти изменения вступают в силу с 30 июня 2025 года для API массовых отчётов. Обязательно внесите соответствующие изменения в обработку отчётов.

Предыдущие версии отчётов будут доступны до 30 сентября 2025 года. После 30 сентября 2025 года предыдущие версии будут упразднены. Обязательно перейдите на последние версии.

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

В следующих таблицах показаны новые версии отчетов для каждого типа отчета:

Отчеты по массовым данным для YouTube Analytics

Системные отчеты — финансовые (не музыкальные)

Системно-управляемые отчеты — нефинансовые

24 апреля 2025 г.

Как было объявлено 26 марта 2025 года , API целевых запросов будет обновлен в рамках нового изменения количества просмотров коротких видео:

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

Эти изменения вступят в силу для API целевых запросов 30 апреля 2025 года. Обязательно скорректируйте свои запросы соответствующим образом.

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

22 апреля 2025 г.

Как было объявлено 7 апреля 2024 года , параметр isCurated больше не поддерживается в отчётах по каналам и плейлистам владельцев контента. С 31 декабря 2024 года этот параметр больше не поддерживается. Он был удалён из отчётов и документации.

26 марта 2025 г.

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

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

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

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

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

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

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

3 марта 2025 г.

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

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

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

15 ноября 2024 г.

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

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

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

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

6 мая 2024 г.

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

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

• Отчет «Одновременные зрители» показывает количество зрителей, одновременно просматривающих различные части одного транслируемого видео.

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

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

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

• startedWatching
• stoppedWatching
• totalSegmentImpressions

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 . Определения каждой метрики см. в документации по метрикам :

  • playlistAverageViewDuration
  • playlistEstimatedMinutesWatched
  • playlistSaves
  • playlistViews

• Поведение метрики 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 . Определения каждой метрики см. в документации по метрикам :

  • playlistAverageViewDuration
  • playlistEstimatedMinutesWatched
  • playlistSaves
  • playlistViews

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

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

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

4 декабря 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 Reporting (массовые отчеты) поддерживают новое значение детализации источника трафика:

• В API YouTube Analytics (целевые запросы), если значение измерения insightTrafficSourceType равно SUBSCRIBER , то значение insightTrafficSourceDetail можно установить равным podcasts , что указывает на то, что трафик был направлен со страницы назначения Podcasts.
• В API YouTube Reporting (Bulk Reports) если значение параметра 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 Reporting (Bulk Reports) параметр gender в настоящее время поддерживает три значения: FEMALE , MALE и GENDER_OTHER . С 11 августа 2022 года набор поддерживаемых значений изменится на FEMALE , MALE и USER_SPECIFIED .

9 февраля 2022 г.

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

• В API YouTube Analytics (целевые запросы) показатели averageViewDuration и averageViewPercentage не включают трафик циклических клипов по состоянию на 13 декабря 2021 г.
• В API YouTube Reporting (Bulk Reports) показатели average_view_duration_seconds и average_view_duration_percentage не включают трафик циклических клипов по состоянию на 13 декабря 2021 г.

2 февраля 2022 г.

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

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

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

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

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

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

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

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 Reporting (массовые отчёты). Подробнее об этих изменениях можно узнать в Справочном центре 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-дневные периоды. Например:

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

27 июня 2019 г.

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

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

1 ноября 2018 г.

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

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

  Обратите внимание, что график прекращения поддержки был первоначально объявлен 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» обновлён, чтобы напомнить вам о возможности использования API данных YouTube для получения дополнительных метаданных ресурсов, указанных в ответах API YouTube Analytics. Как указано в Правилах для разработчиков сервисов API YouTube (разделы III.E.4.b – III.E.4.d), клиенты API должны удалить или обновить сохранённые метаданные ресурсов из этого API по истечении 30 дней.

22 мая 2018 г.

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

• Вступление в силу следующих изменений запланировано на июль 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 , теперь возвращают код ответа HTTP 400 Если вы еще не обновили свое приложение, чтобы использовать показатель estimatedRevenue вместо показателя earnings , сделайте это как можно скорее.

Документация API была обновлена, и в ней удалены оставшиеся ссылки на показатель earnings .

6 июля 2017 г.

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

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

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

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

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

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

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

  • Задания по созданию отчетов для следующих отчетов YouTube Reporting API были удалены:

    • 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 г.

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

• 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 г.

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

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

  • Измерение sharing_service , определяющее службу, которая использовалась для обмена видео, теперь поддерживает следующие значения:
    • 85 : Музыка на YouTube
    • 86 : Игры на YouTube
    • 87 : YouTube Детям
    • 88 : YouTube ТВ

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

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

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

28 марта 2017 г.

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

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

  • adImpressions
  • cpm
  • estimatedAdRevenue
  • estimatedRedPartnerRevenue
  • estimatedRevenue
  • grossRevenue
  • monetizedPlaybacks
  • playbackBasedCpm

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

  • Базовая статистика активности пользователей
  • Активность пользователей по странам за определенные периоды времени
  • Активность пользователей по странам
  • Лучшие видео с дополнительными региональными фильтрами

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

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

17 марта 2017 г.

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

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

  • Метрика redViews определяет количество просмотров видео участниками YouTube Red.
  • Метрика estimatedRedMinutesWatched определяет количество минут, в течение которых участники YouTube Red смотрели видео.

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

3 марта 2017 г.

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

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

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

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

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

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

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

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

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

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

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

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

  • Измерение 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 г.

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

• Отчеты канала

  • channel_basic_a1 — заменен отчетом channel_basic_a2 .
  • channel_province_a1 — заменен отчетом channel_province_a2 .
  • channel_playback_location_a1 — заменен отчетом channel_playback_location_a2 .
  • channel_traffic_source_a1 — заменен отчетом channel_traffic_source_a2 .
  • channel_device_os_a1 — заменен отчетом channel_device_os_a2 .
  • channel_subtitles_a1 — заменен отчетом channel_subtitles_a2 .
  • channel_combined_a1 — заменен отчетом channel_combined_a2 .

• Отчеты владельца контента

  • content_owner_basic_a2 — заменен отчетом content_owner_basic_a3 .
  • content_owner_province_a1 — заменен отчетом content_owner_province_a2 .
  • content_owner_playback_location_a1 — заменен отчетом content_owner_playback_location_a2 .
  • content_owner_traffic_source_a1 — заменен отчетом content_owner_traffic_source_a2 .
  • content_owner_device_os_a1 — заменен отчетом content_owner_device_os_a2 .
  • content_owner_subtitles_a1 — заменен отчетом content_owner_subtitles_a2 .
  • content_owner_combined_a1 — заменен отчетом content_owner_combined_a2 .
  • content_owner_asset_basic_a1 — заменен отчетом content_owner_asset_basic_a2 .
  • content_owner_asset_province_a1 — заменен отчетом content_owner_asset_province_a2 .
  • content_owner_asset_playback_location_a1 — заменен отчетом content_owner_asset_playback_location_a2 .
  • content_owner_asset_traffic_source_a1 — заменен отчетом content_owner_asset_traffic_source_a2 .
  • content_owner_asset_device_os_a1 — заменен отчетом content_owner_asset_device_os_a2 .
  • content_owner_asset_combined_a1 — заменен отчетом content_owner_asset_combined_a2 .

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

11 ноября 2016 г.

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

API отчетов 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 г.)

  • content_owner_ad_performance_a1 — заменен отчетом content_owner_ad_rates_a1 .
  • content_owner_estimated_earnings_a1 — заменен отчетом content_owner_estimated_revenue_a1 .
  • content_owner_asset_estimated_earnings_a1 — заменен отчетом content_owner_asset_estimated_revenue_a1 .

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 Analytics, поскольку партнерам не нужно планировать задания для создания отчетов.

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

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

27 сентября 2016 г.

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

Показатель uniques YouTube Analytics API устарел. Это не основной показатель, и он будет поддерживаться до 31 октября 2016 года.

15 сентября 2016 г.

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

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

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

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

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

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

  • Видеоотчеты канала

    • channel_basic_a2
    • channel_province_a2
    • channel_playback_location_a2
    • channel_traffic_source_a2
    • channel_device_os_a2
    • channel_subtitles_a2
    • channel_combined_a2

  • Видеоотчеты владельцев контента

    • content_owner_basic_a3
    • content_owner_province_a2
    • content_owner_playback_location_a2
    • content_owner_traffic_source_a2
    • content_owner_device_os_a2
    • content_owner_subtitles_a2
    • content_owner_combined_a2

  • Отчеты об объектах владельца контента

    • content_owner_asset_basic_a2
    • content_owner_asset_province_a2
    • content_owner_asset_playback_location_a2
    • content_owner_asset_traffic_source_a2
    • content_owner_asset_device_os_a2
    • content_owner_asset_combined_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 , содержат богатый набор обновлений текущих Условий обслуживания. Помимо обновленных условий , которые вступят в силу 10 февраля 2017 г., это обновление включает в себя несколько подтверждающих документов, которые помогут объяснить политики, которым должны следовать разработчики.

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

10 августа 2016 г.

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

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

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

    Метрики в следующей таблице устарели. В то же время вводятся новые метрики, относящиеся к тем же данным. По сути, это означает, что старые показатели переименовываются, хотя 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 поддерживает два новых значения измерения:
    • CAMPAIGN_CARD : этот источник трафика поддерживается только для отчетов владельцев контента . Это указывает на то, что просмотры были вызваны заявленными пользователями видеороликами, которые владелец контента использовал для продвижения просмотренного контента.
    • END_SCREEN : данные относятся к просмотрам, произошедшим с конечного экрана другого видео.

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

  • Параметр adType теперь поддерживает значение auctionBumperInstream , которое относится к видеообъявлению без возможности пропуска продолжительностью до 6 секунд, которое воспроизводится перед просмотром видео.

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

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

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

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

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

18 июля 2016 г.

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

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

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

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

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

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

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

28 июня 2016 г.

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

• cardImpressions
• cardTeaserImpressions
• cardClicks
• cardTeaserClicks
• cardClickRate
• cardTeaserClickRate

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

• Базовая статистика ( каналы , владельцы контента )
• По времени ( каналы , владельцы контента )
• География пользователей ( каналы , владельцы контента )
• Активность пользователей по статусу подписки ( каналы , владельцы контента )
• Топ видео ( каналы , владельцы контента )

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 в estimated_partner_ad_auction_revenue .
    • Они переименовывают показатель estimated_partner_double_click_revenue в 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_adsense_revenue было обновлено на estimated_partner_ad_sense_revenue . Однако обратите внимание, что этот показатель появляется только в двух отчетах, поддержка которых прекращена в этом обновлении. Как описано выше, в новых версиях этих отчетов этот показатель был переименован в estimated_partner_ad_auction_revenue .
  • Имя показателя estimated_partner_doubleclick_revenue было обновлено на estimated_partner_double_click_revenue . Еще раз обратите внимание, что этот показатель появляется только в двух отчетах, поддержка которых прекращена в этом обновлении. Как описано выше, в новых версиях этих отчетов этот показатель был переименован в estimated_partner_ad_reserved_revenue .

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

19 мая 2016 г.

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

• API поддерживает новую версию отчета об активности пользователей для владельцев контента . Идентификатор типа отчета для нового отчета — 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.

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 .

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

16 марта 2016 г.

This update contains the following changes, which affect both the YouTube Reporting API and the YouTube Analytics API:

API отчетов YouTube

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

API аналитики YouTube

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

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.

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 .

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 .

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
  Метрики:	Use 1 or more views , estimatedMinutesWatched
  Фильтры:	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.

10 ноября 2015 г.

This update contains the following changes:

• The YouTube Analytics API now supports the redPartnerRevenue metric, which reports the total estimated revenue earned from YouTube Red subscriptions for the selected report dimensions. The metric's value reflects earnings from both music and non-music content and is subject to month-end adjustment.

  The YouTube Analytics API's list of content owner reports has been updated to identify the video reports that support the redPartnerRevenue metric:

  • Базовая статистика
  • Основанный на времени
  • User geography
  • Top videos – For this report, redPartnerRevenue is also supported as a sorting metric, which means you can retrieve a list of videos sorted by their YouTube Red earnings.

• The top videos report definition for the YouTube Analytics API now reflects that this report also supports the following earnings metrics: earnings , adEarnings , grossRevenue , monetizedPlaybacks , playbackBasedCpm , impressions , and impressionBasedCpm .

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.

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.

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.

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.

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.

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.

31 марта 2015 г.

This update contains the following changes:

• The favoritesAdded and favoritesRemoved metrics are both deprecated effective as of this announcement. These are both core metrics and subject to the Deprecation Policy set forth in the terms of service .

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.

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.

13 февраля 2015 г.

This update contains the following changes:

• The API no longer supports the show dimension.

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.

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.

  • annotationImpressions : The total number of annotation impressions.
  • annotationClickableImpressions : The number of annotations that appeared and could be clicked.
  • annotationClosableImpressions : The number of annotations that appeared and could be closed.
  • annotationClicks : The total number of clicked annotations.
  • annotationCloses : The total number of closed annotations.

  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 .

31 января 2014 г.

This update contains the following changes:

• The content owner reports document has been updated to reflect that the subscribersGained and subscribersLost metrics can now be retrieved for content claimed or uploaded by a content owner.

  The change is visible in the first basic stats report for content owners, which now supports the claimedStatus and uploaderType filters.

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:

  • Базовая статистика
  • Основанный на времени
  • Географический
  • Место воспроизведения
  • Источник трафика
  • Устройство/ОС
  • Демографические
  • Социальный
  • 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.

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:

  • Базовая статистика
  • Основанный на времени
  • Географический
  • Место воспроизведения
  • Источник трафика
  • Устройство/ОС
  • Демографические
  • Социальный
  • Лучшие видео

  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.

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.

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.

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.

10 мая 2013 г.

This update contains the following changes:

• YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy .

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

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.

28 марта 2013 г.

This update contains the following changes:

• The API now supports two new metrics, annotationClickThroughRate and annotationCloseRate , which are related to viewer interactions with annotations that display during your videos. The lists of channel reports and content owner reports have both been updated to identify the reports that support the new metrics.

  • annotationClickThroughRate – The ratio of annotations that viewers clicked to the total number of clickable annotation impressions.
  • annotationCloseRate – The ratio of annotations that viewers closed to the total number of annotation impressions.

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 .

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.

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.

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 .

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.