Introduction

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

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

  • Отчеты по каналам содержат показатели активности пользователей для указанного канала.

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

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

Все запросы API YouTube Analytics и YouTube Reporting должны быть авторизованы владельцем канала или контента, которому принадлежат запрашиваемые данные.

Содержание отчета

Отчеты, которые извлекают API, содержат два типа данных:

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

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

  • Метрики — это индивидуальные измерения активности пользователя, эффективности рекламы или предполагаемого дохода. Метрики активности пользователя включают такие вещи, как количество просмотров видео и рейтинги (лайки и дизлайки).

Выберите правильный API для вашего приложения

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

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

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

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

Поддерживаемые отчеты

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

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

Типы отчетов
Видео отчеты Поддерживается для каналов ( запрос или массовая рассылка ) и владельцев контента ( запрос или массовая рассылка ).

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

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

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

Отчеты о предполагаемом доходе предоставляют общий предполагаемый доход для видео из источников рекламы, проданных Google, и из нерекламных источников. Эти отчеты также содержат некоторые показатели эффективности рекламы. Обратите внимание, что отчеты, управляемые системой, содержат фактический доход.
Отчеты об активах Поддерживается для владельцев контента ( массово ).

Отчеты об активах предоставляют метрики активности пользователей, связанные с видео, которые связаны с активами владельца контента. Видео включается в отчет владельца контента, если владелец контента заявил, что это видео соответствует одному из активов владельца контента. Видео могло быть загружено владельцем контента или другим пользователем YouTube.
Системно-управляемые отчеты Поддерживается для владельцев контента, имеющих доступ к соответствующим отчетам в меню «Отчеты» Творческой студии YouTube.

Системно-управляемые отчеты предоставляют фактические данные о доходах, полученных от активов и видео. Дополнительный отчет содержит список заявленных видео и активов, которым соответствуют эти видео. Не все отчеты Creator Studio доступны в API.

Примечание: YouTube автоматически генерирует системно-управляемые отчеты для владельцев контента, имеющих доступ к соответствующим отчетам в Creator Studio. В результате процесс получения этих отчетов отличается от других типов отчетов в этом списке. Для получения дополнительной информации см. документацию по системно-управляемым отчетам .

Ключевые отличия

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

Особенность API аналитики YouTube API отчетов YouTube
Процесс извлечения данных В каждом запросе API указываются возвращаемые измерения и показатели, а также период времени, за который будут возвращены данные. Приложения планируют задания по отчетности. Для каждого задания YouTube генерирует ежедневные отчеты, которые можно асинхронно загружать.
Диапазоны дат Некоторые отчеты API указывают дату, когда произошла активность пользователя. Некоторые из этих отчетов поддерживают измерения для агрегации метрик активности пользователя по месяцам. Все отчеты API указывают день, когда произошла активность пользователя. Приложения, использующие API, могут реализовывать функции для агрегации данных за периодические интервалы.
Фильтрация данных Вы можете фильтровать отчеты, чтобы включить только строки, для которых измерение имеет определенное значение. API также поддерживает некоторые измерения, такие как continent и subContinent , которые используются только как фильтры. API поддерживает массовую загрузку полных наборов данных. Он не поддерживает фильтрацию или возврат данных для измерений, предназначенных только для фильтрации. Клиентское приложение сохраняет загруженные данные и реализует собственные функции для фильтрации данных.
Сортировка Отчеты можно сортировать на основе возвращаемых значений метрик. Некоторые отчеты поддерживают только ограниченное количество результатов. Например, отчет, в котором перечислены наиболее просматриваемые видео канала, возвращает максимум 200 строк. Этот API поддерживает массовые загрузки полных наборов данных. Клиентские приложения могут реализовывать собственные функции для сортировки загруженных данных.
Перечисления Отчеты API содержат текстовые значения, такие как «ANDROID» или «CHANNEL», для идентификации перечисляемых значений измерений. Отчеты API содержат целые числа, которые можно сопоставить с текстовыми значениями.
Квота API-сервер оценивает каждый запрос, чтобы определить его стоимость квоты. Раздел об использовании квоты объясняет методологию более подробно. Использование квоты не является проблемой, поскольку данные извлекаются один раз, а затем фильтруются, сортируются и запрашиваются в приложении.
Уникальные отчеты
  • Активность пользователей, связанная с субтитрами
  • Данные об удержании аудитории для плейлистов
  • Расчетные отчеты о доходах для владельцев контента (доступно 2 различных отчета)
  • Отчеты об активах для владельцев контента (доступно 11 различных отчетов)
Уникальные размеры группа (только фильтруемое измерение)
континент (только фильтруемое измерение)
субконтинент (только фильтруемое измерение)
месяц
просмотрыPerPlaylistStart
среднееВремяВПлейлисте
annotation_id
тип_аннотации
актив_id
идентификатор_карты
тип_карты
в прямом эфире или по запросу
статус_подписки
язык_подзаголовков
Уникальные метрики уникальные
относительноеУдержаниеПроизводительность
просмотрыPerPlaylistStart
среднееВремяВПлейлисте
скорость_щелчка_карты
card_clicks
card_impressions
частота_щелчков_по_карте_тизеру
клики_по_карте_тизеру
card_teaser_impressions
предполагаемый_доход_партнера_adsense
предполагаемый_доход_партнера_doubleclick_playlist_saves_added
плейлист_сохранения_удалены

Различия в наименованиях между API

Эти два API используют разные соглашения об именовании для идентификации измерений и метрик. Имена API YouTube Analytics используют camelCase, например adType . Имена API YouTube Reporting пишутся строчными буквами и используют подчеркивания, например ad_type .

В следующих таблицах указаны различные имена, которые два API используют для идентификации одних и тех же метрик и измерений. В некоторых случаях разница между двумя именами больше, чем та, которую вы получили бы после преобразования имени из camelCase в подчеркивания. Например, измерение video в API YouTube Analytics называется video_id в API YouTube Reporting.

Размеры

Имя API YouTube Analytics Имя API отчетов YouTube
Тип объявления тип_рекламы
возрастная группа возрастная_группа
объект актив_id
Тип аудитории тип_удержания_аудитории
канал идентификатор_канала
заявленныйСтатус заявленный_статус
contentOwner идентификатор_владельца_контента
страна код_страны
день дата
Тип устройства тип_устройства
прошедшееВидеоВремяСоотношение прошедшее_время_видео_процент
пол пол
insightВоспроизведениеРасположениеДеталь сведения_о_местоположении_воспроизведения
insightВоспроизведениеРасположениеТип тип_местоположения_воспроизведения
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType тип_источника_трафика
liveOrOnDemand в прямом эфире или по запросу
Операционная система Операционная система
плейлист плейлист_id
провинция код_провинции
обменСервис обмен_услугами
подписанСтатус статус_подписки
подзаголовокЯзык язык_подзаголовков
ЗагрузчикТип тип_загрузчика
видео видео_id

Метрики

Имя API YouTube Analytics Имя API отчетов YouTube
adВпечатления ad_impressions
аннотацияКликабельноВпечатления annotation_clickable_impressions
аннотацияКлики аннотация_щелчки
аннотацияClickThroughRate annotation_click_through_rate
аннотацияЗакрываемыеВпечатления annotation_closable_impressions
аннотацияЗакрывается annotation_closes
аннотацияЗакрытьОценить annotation_close_rate
аннотацияВпечатления annotation_impressions
аудиторияWatchRatio процент_удержания_аудитории
средняяПродолжительностьПросмотра средняя_продолжительность_просмотра_секунд
среднийПросмотрПроцент средний_процент_длительности_просмотра
cardClickRate скорость_щелчка_карты
cardClicks card_clicks
карточкаВпечатления card_impressions
cardTeaserClickRate частота_щелчков_по_карте_тизеру
cardTeaserClicks клики_по_карте_тизеру
карточкаТизерВпечатления card_teaser_impressions
комментарии комментарии
cpm расчетная_cpm
не нравится не нравится
расчетныйAdRevenue предполагаемый_доход_от_рекламы_партнера
Оценочное количество просмотренных минут watch_time_minutes
Предполагаемый доход предполагаемый_доход_партнера
валовой доход предполагаемый_доход_от_рекламы_youtube
нравится нравится
монетизированоВоспроизведения предполагаемые_монетизированные_воспроизведения
playbackBasedCpm расчетная_cpm_на_основе_воспроизведения
плейлистStarts playlist_starts
сохраняетДобавлено playlist_saves_added
сохраняетУдален плейлист_сохранения_удалены
акции акции
подписчикиПриобретены подписчики_приобретены
подписчикиПотерянные подписчики_потеряны
видеоДобавлено в плейлисты видео_добавлены_в_плейлисты
видеоУдаленоИзПлейлистов видео_удалены_из_плейлиста
Процент зрителей просмотры_процент
просмотров просмотров