Introduction

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

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

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

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

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

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

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

Отчеты, которые получают 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.

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

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

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

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

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

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

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

Отчеты, управляемые системой, предоставляют фактические данные о доходах, полученных от объектов и видео. В дополнительном отчете перечислены видео, на которые заявлены права, и объекты, которым эти видео соответствуют. Обратите внимание, что не все отчеты Creator Studio в настоящее время доступны в API.

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

Ключевые различия

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

Особенность API YouTube Аналитики API отчетов YouTube
Процесс получения данных В каждом запросе API указываются возвращаемые параметры и показатели, а также период времени, за который будут возвращены данные. Приложения планируют задания отчетов. По каждому заданию YouTube создает ежедневные отчеты, которые можно загрузить асинхронно.
Диапазоны дат В некоторых отчетах API указывается дата активности пользователя. Некоторые из этих отчетов поддерживают измерения для агрегирования показателей активности пользователей по месяцам. Во всех отчетах API указан день активности пользователя. Приложения, использующие API, могут реализовывать функции для агрегирования данных за периодические интервалы.
Фильтрация данных Вы можете фильтровать отчеты, чтобы включать только строки, для которых измерение имеет определенное значение. API также поддерживает некоторые измерения, такие как континент и субконтинент , которые используются только в качестве фильтров. API поддерживает массовую загрузку полных наборов данных. Он не поддерживает фильтрацию и возврат данных для измерений, в которых используется только фильтр. Клиентское приложение сохраняет загруженные данные и реализует собственные функции для фильтрации данных.
Сортировка Отчеты можно сортировать на основе возвращаемых значений метрик. Некоторые отчеты поддерживают только ограниченное количество результатов. Например, отчет, в котором перечислены наиболее просматриваемые видео канала, возвращает максимум 200 строк. Этот API поддерживает массовую загрузку полных наборов данных. Клиентские приложения могут реализовывать собственные функции для сортировки загружаемых данных.
Перечисления Отчеты API содержат текстовые значения, например «ANDROID» или «CHANNEL», для идентификации перечисляемых значений измерений. Отчеты API содержат целые числа, которые можно сопоставить с текстовыми значениями.
Квота Сервер API оценивает каждый запрос, чтобы определить стоимость его квоты. В разделе «Использование квот» методология объясняется более подробно. Использование квоты не является проблемой, поскольку данные извлекаются один раз, а затем фильтруются, сортируются и запрашиваются внутри приложения.
Уникальные отчеты
  • Действия пользователей, связанные с субтитрами
  • Данные об удержании аудитории для плейлистов
  • Отчеты о предполагаемых доходах для владельцев контента (доступно 2 разных отчета)
  • Отчеты об активах для владельцев контента (доступно 11 различных отчетов)
Уникальные размеры группа (параметр только для фильтра)
континент (измерение, доступное только для фильтра)
субконтинент (измерение, доступное только для фильтра)
месяц
isCurated ==1 (параметр, доступный только для фильтра)
просмотровPerPlaylistStart
среднее время в плейлисте
annotation_id
тип_аннотации
актив_ид
card_id
тип карты
live_or_on_demand
статус_подписки
язык субтитров
Уникальные метрики уникальные
относительная производительность удержания
просмотровPerPlaylistStart
среднее время в плейлисте
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
оцененный_partner_adsense_revenue
оцененный_partner_doubleclick_revenue playlist_saves_added
playlist_saves_removed

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

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

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

Размеры

Название API YouTube Analytics Название API отчетов YouTube
тип объявления тип_объявления
возрастная группа возрастная группа
объект актив_ид
Тип аудитории Audience_retention_type
канал идентификатор_канала
заявленный статус заявленный_статус
владелец контента content_owner_id
страна код страны
день дата
тип устройства тип устройства
elapsedVideoTimeRatio elapsed_video_time_percentage
пол пол
пониманиеВоспроизведениеМестоположениеПодробно player_location_detail
InsightPlaybackLocationType тип воспроизведения_location_type
пониманиеТрафикИсточникПодробно Traffic_source_detail
InsightTrafficSourceType тип_источника_трафика
liveOrOnDemand live_or_on_demand
Операционная система Операционная система
список воспроизведения playlist_id
провинция код_провинции
служба совместного использования общий_сервис
статус подписки статус_подписки
Язык субтитров язык субтитров
тип загрузчика uploader_type
видео video_id

Метрики

Название API YouTube Analytics Название API отчетов YouTube
рекламаЗаработок оцененный_partner_ad_revenue
аннотацияВпечатления annotation_impressions
аннотацияClickableImpressions annotation_clickable_impressions
аннотацияКлики annotation_clicks
аннотацияClickThroughRate annotation_click_through_rate
аннотацияClosableImpressions annotation_closable_impressions
аннотацияCloses аннотация_закрывается
аннотацияCloseRate annotation_close_rate
аудиторияWatchRatio Audience_retention_percentage
средняя продолжительность просмотра Average_view_duration_секунды
среднийViewPercentage Average_view_duration_percentage
картаClickRate card_click_rate
картаКлики card_clicks
картыПоказы card_impressions
картаТизерКликОценка card_teaser_click_rate
картыТизерКлики card_teaser_clicks
cardТизерВпечатления card_teaser_impressions
Комментарии Комментарии
не любит не любит
заработок оцененный_partner_revenue
расчетное количество минут просмотра смотреть_время_минуты
расчетный доход партнераAdSense оцененный_partner_adsense_revenue
расчетный доходPartnerDoubleClick оцененный_partner_doubleclick_revenue
валовой доход оцененный_youtube_ad_revenue
Цена за тысячу показов на основе показов расчетная_цена за тысячу показов
впечатления рекламные_показы
нравится нравится
монетизированоВоспроизведения оцененные_монетизированные_воспроизведения
воспроизведение на основе цены за тысячу показов оцененная_playback_based_cpm
плейлистНачинается playlist_starts
СохраненияДобавлено playlist_saves_added
сохранения удалены playlist_saves_removed
акции акции
подписчиковПриобретено подписчики_получены
подписчикиПотеряны подписчики_потеряны
видеоДобавленоВплейлисты videos_added_to_playlists
ВидеоУдаленоИзПлейлистов videos_removed_from_playlist
Процент зрителя просмотров_процента
Просмотры Просмотры