Эта страница переведена с помощью Cloud Translation API.

YouTube Analytics API - Data Model

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

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

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

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

При запросе отчета с помощью метода reports.query API, запрос содержит пять параметров, определяющих способ расчета значений отчета:

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

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

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

Владелец канала устанавливает параметр startDate равным 2015-06-01 и параметр endDate равным 2015-07-31 . На основе этих значений отчет будет содержать данные за двухмесячный период.
Отчет по типам устройств поддерживает метрики views и estimatedMinutesWatched , поэтому владелец канала устанавливает параметр 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 года?)

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

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

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

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

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

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

Передовые методы

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограниченное количество типов данных

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

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

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

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

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