YouTube Analytics API - Data Model

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

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

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

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

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

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

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

  • Параметры startDate и endDate задают период времени, за который отчёт будет содержать данные. Ответ API фактически содержит данные до последнего указанного дня, для которого все метрики в запросе доступны на момент выполнения запроса.

  • Параметр metrics определяет, какие показатели будут включены в отчёт. В отчётах по каналам метрики измеряют активность пользователей и включают такие значения, как просмотры и отметки «Нравится» . Некоторые метрики также измеряют эффективность рекламы или предполагаемый доход.

  • Параметр dimensions объясняет, как будут сгруппированы показатели.

  • Параметр filters определяет, как будут фильтроваться данные отчёта. Например, вместо того, чтобы возвращать все данные по каналу, отчёт можно отфильтровать так, чтобы он содержал только показатели по определённой стране, видео или группе видео.

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

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

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

  • Владелец канала устанавливает параметр startDate на 2015-06-01 и параметр endDate на 2015-07-31 . На основе этих значений отчёт будет содержать данные за двухмесячный период.

  • Отчет по типу устройства поддерживает метрики views и estimateMinutesWatched , поэтому владелец канала устанавливает параметр metrics на views,estimatedMinutesWatched .

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

    • Установка значения параметра deviceType означает, что количество просмотров и время просмотра будут сгруппированы по типу устройства за весь период, охватываемый отчётом. Таким образом, при этом значении данные отчёта будут отвечать на такие вопросы, как:

      • Сколько раз видео канала были просмотрены на мобильных устройствах в период с 1 июня 2015 г. по 31 июля 2015 г.?
      • Сколько раз видео канала были просмотрены на игровых консолях в период с 1 июня 2015 г. по 31 июля 2015 г.?

      Фактически отчет будет содержать общее количество просмотров и времени просмотра для каждого типа устройства.

    • Установка значения параметра day,deviceType означает, что количество просмотров и время просмотра будут рассчитываться по типу устройства для каждого дня в течение отчётного периода. Таким образом, при этом значении данные отчёта будут отвечать на такие вопросы, как:

      • Сколько раз видео канала были просмотрены на мобильных устройствах 1 июня 2015 года?
      • Сколько раз видеоролики канала были просмотрены по телевизору 14 июля 2015 года?

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

    • Владелец канала может отфильтровать запрос, чтобы возвращать значения только для операционной системы Android. (Сколько просмотров было совершено на мобильных устройствах Android за отчётный период?)

    • Владелец канала может отфильтровать запрос, чтобы вернуть значения только для определённой страны. (Сколько раз видео просматривалось в Канаде в каждый день отчётного периода?)

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

      Кроме того, если фильтр видео задаёт несколько значений, то параметр «видео» также может быть указан как измерение. Это означает, что параметр dimensions также поддерживает значения deviceType,video и day,deviceType,video .

      • Если владелец канала включает видео в список измерений, то метрики указывают индивидуальные значения для каждого видео. (Сколько раз видео XYZ было просмотрено на игровой консоли 1 июня 2015 года?)
      • Если владелец канала не включает видео в список измерений, то метрики указывают общие значения, охватывающие все указанные видео. (Сколько раз видео ABC, DEF и XYZ были просмотрены на игровой консоли 1 июня 2015 года?)

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

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

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

Лучшие практики

Приложения, использующие API YouTube Analytics, всегда должны следовать следующим правилам:

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

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

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

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

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

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

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

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

    или

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

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

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

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

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

Ограниченные типы данных

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

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

Дополнительную информацию об ограниченных данных в отчетах YouTube Analytics см. в Справочном центре YouTube .

Использование квоты

Каждый ваш запрос к API учитывается как одна единица вашей квоты использования API. Ограничения квоты отображаются на панели «Квоты» в консоли API Google.