Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

YouTube Analytics API - Data Model

YouTube Analytics API позволяет создавать специальные отчеты с данными из YouTube Аналитики. API поддерживает отчеты для каналов и владельцев контента. Поля отчетов делятся на параметры и показатели.

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

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

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

Выбор параметров отчета

Когда вы запрашиваете отчет с помощью метода reports.query, запрос к API содержит пять параметров, которые определяют, как будут рассчитываться значения в отчете:

Параметры startDate и endDate определяют период времени, за который в отчете будут представлены данные. Ответ API содержит данные до последнего указанного дня, за который на момент запроса доступны все показатели в запросе.
Параметр metrics определяет, какие показатели будут включены в отчет. В отчетах по каналам показатели отражают действия пользователей и включают такие значения, как просмотры и отметки "Нравится". Некоторые показатели также измеряют эффективность рекламы или расчетный доход.
Параметр dimensions определяет, как будут сгруппированы показатели.
Параметр filters определяет, как будут фильтроваться данные отчета. Например, вместо того чтобы возвращать все данные по каналу, отчет можно отфильтровать так, чтобы он содержал только показатели по определенной стране, видео или группе видео.

Примечание. API позволяет указать несколько значений для фильтров video, playlist и channel. Если вы это сделаете, то сможете включить этот фильтр в список параметров, чтобы возвращаемые показатели также группировались по видео, плейлисту или каналу.

Примеры вариантов отчетов

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

Владелец канала задает для параметра startDate значение 2015-06-01, а для параметра endDate – значение 2015-07-31. В этом случае в отчет будут включены данные за два месяца.
Отчет по типам устройств поддерживает показатели views и estimatedMinutesWatched, поэтому владелец канала задает для параметра metrics значение views,estimatedMinutesWatched.
Для параметра dimensions владелец канала может выбрать один из нескольких вариантов. Два из них приведены в списке ниже, а третий рассматривается в описании значения параметра filters далее в этом разделе.
- Если задать для параметра значение deviceType, то количество просмотров и время просмотра будут сгруппированы по типу устройства за весь период, охватываемый отчетом. Таким образом, с помощью этого значения данные отчёта ответят на такие вопросы, как:
- Сколько раз видео на канале были просмотрены на мобильных устройствах в период с 1 июня по 31 июля 2015 года?
- Сколько раз видео на канале были просмотрены на игровых консолях в период с 1 июня по 31 июля 2015 года?
В отчете будет указано общее количество просмотров и время просмотра для каждого типа устройств.
- Если задать для параметра значение day,deviceType, то количество просмотров и время просмотра будут рассчитываться по типу устройства за каждый день в течение отчетного периода. Таким образом, с помощью этого значения данные отчёта ответят на такие вопросы, как:
- Сколько раз видео на канале были просмотрены на мобильных устройствах 1 июня 2015 года?
- Сколько раз видео на канале посмотрели на телевизорах 14 июля 2015 года?
Наконец, параметр filters позволяет владельцу канала ограничить отчет, включив в него только данные, соответствующие определенным значениям фильтра. В отчете поддерживается слишком много вариантов фильтрации, чтобы описать их все, поэтому в примерах ниже показана лишь малая часть отчетов, которые можно создать.
- Владелец канала может отфильтровать запрос, чтобы получить значения только для операционной системы Android. (Сколько просмотров было выполнено на мобильных устройствах Android за отчетный период?)
- Владелец канала может отфильтровать запрос, чтобы получить значения только для определенной страны. (Сколько раз видео просматривали в Канаде в каждый день отчетного периода?)
- Владелец канала может отфильтровать запрос, чтобы получить значения только для определенных видео. Однако фильтр video поддерживает список значений, разделенных запятыми, поэтому отчет может содержать данные по нескольким видео.
Кроме того, если в фильтре video указано несколько значений, то video также можно задать в качестве параметра. Это означает, что параметр dimensions также поддерживает значения deviceType,video и day,deviceType,video.
- Если владелец канала включит в список параметров видео, то показатели будут содержать отдельные значения для каждого видео. (Сколько раз видео XYZ было просмотрено на игровой консоли 1 июня 2015 г.?)
- Если владелец канала не включит видео в список параметров, то показатели будут отражать общие значения для всех указанных видео. (Сколько раз видео ABC, DEF и XYZ были просмотрены на игровой консоли 1 июня 2015 года?)

Актуальность данных и задержка

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

Из-за задержки данных вы можете заметить расхождения между данными, возвращаемыми API, и показателями в реальном времени, видимыми в Творческой студии YouTube. Если вашему приложению требуется статистика по отдельным видео в реальном времени, например текущее количество просмотров, лайков или комментариев, используйте метод videos.list YouTube Data API вместо YouTube Analytics API.

Получение отчетов

Чтобы получить отчет, отправьте авторизованный GET-запрос к методу reports.query API, указав параметры, определяющие нужный отчет.

Список отчетов, поддерживаемых API, можно найти в документации по отчетам для каналов и отчетам для владельцев контента. В каждом определении отчета указаны значения, которые отчет позволяет использовать для параметров metrics, dimensions и filters.

Агрегированные показатели и удаленные объекты

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

Предположим, что владелец канала получает два отчета. В первом отчете указано общее количество просмотров всех видео на канале за определенный период времени. Второй отчет содержит данные о количестве просмотров каждого видео за тот же период времени.

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

Анонимизация данных

Некоторые данные в YouTube Аналитике могут быть недоступны, если показатели не достигли минимальных значений. Это может произойти в различных отчетах. На практике это означает, что отчет может не содержать всех или некоторых данных, если:

видео или канал набрали недостаточно трафика за указанный период времени;

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

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

Предположим, что владелец канала получает два отчета. В первом отчете указано общее количество просмотров определенного видео, а во втором – общее количество просмотров этого видео с разбивкой по странам. Допустим, за указанный период времени видео набрало 1000 просмотров: 500 в США, 498 в Канаде и 2 во Франции.

В этом примере в первом отчете будет указано, что видео набрало 1000 просмотров. Во втором отчете будет указано, что видео набрало 500 просмотров в США и 498 в Канаде. Таким образом, будет разница между общим числом просмотров в двух отчетах. Обратите внимание, что во втором отчете не будет указано, что было ещё два просмотра (или что просмотры были во Франции).

Некоторые типы данных

В отчетах YouTube Аналитики могут быть недоступны следующие данные:

Демографические данные, например возраст и пол.
Географические данные, в том числе показатели и параметры, связанные со странами и регионами, в которых находятся зрители. Однако обратите внимание, что в отчетах не применяются пороговые значения по географическому признаку к показателям дохода.
Показатели, связанные с определенными источниками трафика, например поисковыми запросами или внешними URL, которые привели к просмотрам ваших видео. Например, в отчетах не будут показываться поисковые запросы и URL, которые привели к небольшому количеству просмотров. При этом вы по-прежнему будете видеть запросы и URL, которые привлекли много зрителей.

Подробнее об ограниченных данных в отчетах YouTube Аналитики написано в Справочном центре YouTube.

Расход квоты

Каждый запрос к API считается за одну единицу квоты на использование API. Ограничения квот можно посмотреть на панели Quotas (Квоты) в консоли Google Cloud.