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

YouTube Analytics API - Data Model

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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