YouTube Analytics API: Channel Reports

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

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

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

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

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

• channel==MINE – API возвращает данные для канала YouTube аутентифицированного пользователя.

• channel== CHANNEL_ID – Задайте в качестве CHANNEL_ID уникальный идентификатор канала, данные по которому вы получаете. Пользователь, авторизующий запрос, должен быть владельцем канала.

  В настоящее время идентификатор канала представляет собой строку, начинающуюся с букв UC , хотя её формат может измениться. (Идентификатор канала можно найти на странице расширенных настроек учётной записи вашего канала YouTube или получить его программным способом с помощью метода channels.list YouTube Data API's .)

Авторизация

Все запросы к API YouTube Analytics должны быть авторизованы. В руководстве по авторизации объясняется, как использовать протокол OAuth 2.0 для получения токенов авторизации.

Запросы API YouTube Analytics используют следующие области авторизации:

Примечание: Показатели предполагаемого дохода и эффективности рекламы в настоящее время не поддерживаются для отчётов по каналам. В связи с этим область действия https://www.googleapis.com/auth/yt-analytics-monetary.readonly в настоящее время не предоставляет доступ к денежным данным в этих отчётах.

Фильтры

В таблицах, описывающих поддерживаемые отчёты, указаны фильтры, которые можно использовать для каждого отчёта. Фильтры, указанные в скобках, являются необязательными. Например, для параметра фильтрации video(,country) фильтр по видео обязателен, а фильтр по стране — необязателен.

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

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

Понимание таблиц отчетов

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

Таблица содержит две строки для измерений, одну строку для метрик и три строки для фильтров. Для измерений и фильтров значения из каждой строки можно объединять в запросе API, если эта комбинация соответствует правилам использования, указанным в таблице. Например, допустимые значения параметров dimensions для этого отчёта включают:

• dimensions=day
• dimensions=day,subscribedStatus
• dimensions=month,subscribedStatus,youtubeProduct
• dimensions=month,youtubeProduct

Однако значение параметра day,month недопустимо, поскольку оно использует два временных измерения, а запрос должен использовать либо 0, либо 1.

Терминология таблицы отчетов

Для указания обязательности или необязательности измерений в таблицах используется следующая терминология:

• Эти термины означают, что требуется значение:
  • Обязательно: необходимо указать значение.
  • Используйте ровно 1: необходимо включить одно значение из группы.
  • Используйте 1 или более: вы можете включить любое или все значения из группы, но необходимо включить хотя бы одно.
• Эти термины означают, что значение является необязательным:
  • Необязательно: у вас есть возможность включить значение.
  • Используйте 0 или 1: у вас есть возможность включить одно значение из группы.
  • Используйте 0 или более: у вас есть возможность включить любое или все значения из группы.

Видеоотчеты

Базовая статистика

Базовая статистика активности пользователей

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

Базовая статистика активности пользователей по штатам США

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

Основанный на времени

Активность пользователей по странам за определенные периоды времени

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

Активность пользователей в штатах США за определенные периоды времени

Этот отчёт содержит статистику активности пользователей в конкретном штате США или округе Колумбия. Обратите внимание, что этот отчёт поддерживает только часть показателей, доступных в отчёте по конкретной стране, описанном выше.

География пользователей

Активность пользователей по странам

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

Активность пользователей по провинциям

Этот отчёт содержит статистику активности пользователей в штатах США и округе Колумбия. Для этого отчёта необходимо установить значение параметра filters country==US .

Активность пользователей по городам (<= 250 результатов)

Примечание: для этого отчёта необходимо задать параметру maxResults целое значение не более 250 В отличие от большинства других отчётов, для этого отчёта также требуется указать значение параметра запроса sort .

В этом отчете представлена ​​статистика активности пользователей по городам.

Активность пользователей по DMA

Этот отчёт предоставляет статистику активности пользователей по выделенному рынку (DMA). Для этого отчёта необходимо либо установить значение параметра filters « country==US , либо выбрать конкретную провинцию (штат США).

Подробности воспроизведения

Подробные отчеты о воспроизведении содержат статистику по следующим атрибутам просмотра:

• Транслировалось ли видео в прямом эфире или по запросу?
• Был ли зритель подписан на канал, которому принадлежит видео?
• На каком продукте YouTube произошел просмотр?

Примечание: измерение и фильтр liveOrOnDemand нельзя использовать вместе с метрикой averageViewPercentage . В связи с этим в каждом из следующих подразделов представлены два отчёта. Один отчёт поддерживает измерение (и фильтр) liveOrOnDemand , а другой — метрику averageViewPercentage .

Активность пользователя по статусу подписки

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

Активность пользователей по статусу подписки для провинций

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

Подробности воспроизведения с дополнительным измерением времени

Указание времени ( день или месяц ) для этих отчётов необязательно, поскольку в любом случае необходимо использовать параметры запроса startDate и endDate для указания диапазона дат, который будет охватываться отчётом. Если указание этого параметра присутствует, данные в отчёте должны быть агрегированы по дню, месяцу и т. д.

Подробная информация о воспроизведении с дополнительным измерением времени и статистикой liveOrOnDemand

Этот отчёт содержит подробную статистику воспроизведения за определённые временные интервалы. Он поддерживает параметр liveOrOnDemand (и фильтр).

Подробности воспроизведения с дополнительным измерением времени и метрикой averageViewPercentage

Этот отчёт предоставляет подробную статистику воспроизведения за определённые временные интервалы. Он поддерживает метрику AverageViewPercentage .

Подробности воспроизведения по странам

Подробная информация о воспроизведении по странам со статистикой liveOrOnDemand

Этот отчёт содержит подробную статистику воспроизведения по странам. Он поддерживает параметр liveOrOnDemand (и фильтр).

Подробная информация о воспроизведении по странам с метрикой AverageViewPercentage

Следующий отчёт аналогичен предыдущему. Он добавляет поддержку метрики averageViewPercentage , но не поддерживает liveOrOnDemand как параметр или фильтр.

Подробности воспроизведения по провинциям

Воспроизведение данных по провинциям со статистикой liveOrOnDemand

Этот отчёт содержит подробную статистику воспроизведения по штатам США и округу Колумбия. Он поддерживает параметр liveOrOnDemand (и фильтр).

Подробности воспроизведения по провинциям с метрикой AverageViewPercentage

Следующий отчёт аналогичен предыдущему. Он добавляет поддержку метрики averageViewPercentage , но не поддерживает liveOrOnDemand как параметр или фильтр.

Места воспроизведения

Отчет о месте воспроизведения видео

В этом отчете представлена ​​статистика, связанная с типом страницы или приложения, где происходило воспроизведение видео.

Подробности места воспроизведения (<= 25 результатов)

Примечание: для этого отчёта необходимо задать для параметра maxResults целое значение не более 25 В отличие от большинства других отчётов, для этого отчёта также требуется указать значение параметра запроса sort .

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

Источники трафика

Источник трафика

Этот отчёт собирает статистику просмотров на основе способов, которыми зрители получили доступ к вашему видеоконтенту. Например, он определяет количество просмотров, полученных через поиск Google или по ссылке на похожее видео.

Примечание: Этот отчёт возвращает ошибку, если произведение количества запрошенных видео на количество дней в диапазоне дат превышает 50 000. Например, запрос, извлекающий данные по 500 идентификаторам видео, может запросить данные максимум за 100 дней. Чтобы уменьшить количество возвращаемых строк, разделите запрос на несколько запросов, указывающих меньшее количество видео или задающих более короткие диапазоны дат.

Подробная информация об источнике трафика (<= 25 результатов)

Примечание: для этого отчёта необходимо задать для параметра maxResults целое значение не более 25 В отличие от большинства других отчётов, для этого отчёта также требуется указать значение параметра запроса sort .

Этот отчёт агрегирует статистику просмотров на основе рефереров, сгенерировавших наибольшее количество просмотров контента канала. Рефереры классифицируются по типу источника трафика, а определение измерения insightTrafficSourceDetail определяет источники трафика, для которых доступен отчёт. Например, если для фильтра insightTrafficSourceType установлено значение ADVERTISING , в отчёте будут перечислены типы рекламы, сгенерировавшие наибольшее количество просмотров или времени просмотра контента канала.

Примечание: этот отчёт поддерживается только для определённых источников трафика. Источники трафика VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED — некоторые из неподдерживаемых.

Тип устройства и операционная система

Тип устройства

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

Операционная система

В этом отчёте собрана статистика просмотров по операционным системам зрителей. Например, он определяет количество просмотров на устройствах Android или PlayStation.

Операционная система и тип устройства

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

Демографические данные зрителей

В этом отчете собрана статистика просмотров в зависимости от возрастной группы и пола зрителей.

Взаимодействие и обмен контентом

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

Удержание аудитории

Этот отчёт измеряет способность видео удерживать аудиторию, а также показывает, как часто пользователи просматривали определённые фрагменты видео. Параметр elapsedVideoTimeRatio измеряет продолжительность видео, прошедшую с соответствующими значениями метрики. Метрики можно разделить на две категории:

• Удержание аудитории

  Эти показатели показывают, насколько хорошо видео удерживает свою аудиторию.

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

• Подробная статистика просмотра

  Эти показатели предоставляют информацию о том, как часто просматривались определенные части видео.

  • startedWatching показывает, как часто зрители начинали просмотр видео во время определенного сегмента видео.
  • stoppedWatching показывает, как часто зрители прекращали просмотр видео во время определенного его фрагмента.
  • totalSegmentImpressions показывает, как часто просматривался определенный фрагмент видео.

Примечание: этот отчет не поддерживает возможность указания списка значений, разделенных запятыми, для video ; значение должно указывать один идентификатор видео.

Одновременные зрители (для прямых трансляций)

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

Лучшие видео

Примечание: для этих отчётов необходимо задать для параметра maxResults целое значение не более 200 До 1 января 2013 года данные доступны только для 10 лучших видео. В отличие от большинства других отчётов, для этих отчётов также требуется указать значение параметра запроса sort .

Лучшие видео с дополнительными региональными фильтрами (<= 200 результатов)

В этом отчёте представлены лучшие видео канала. Отчёт можно фильтровать по странам , континентам и субконтинентам .

Лучшие видео по штату (<= 200 результатов)

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

Лучшие видео для подписавшихся и неподписавшихся зрителей (<= 200 результатов)

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

Лучшие видео по продукту YouTube (<= 200 результатов)

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

Лучшие видео с фильтрами детализации воспроизведения (<= 200 результатов)

В этом отчёте перечислены самые популярные видео канала, отфильтрованные по любому или всем параметрам воспроизведения: liveOrOnDemand , subscribedStatus и youtubeProduct . В отличие от предыдущего отчёта, этот поддерживает фильтр liveOrOnDemand и не поддерживает метрику averageViewPercentage .

Отчеты о плейлистах

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

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

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

Список агрегированных метрик видео, поддерживаемых YouTube, см. в разделе поддерживаемых метрик плейлистов .

Метрики в плейлисте

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

Поддерживаемые метрики плейлиста

Базовая статистика

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

Основанный на времени

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

География пользователей

Активность плейлиста по странам

В этом отчете представлена ​​статистика взаимодействия пользователей в определенной стране с видеороликами в плейлистах канала.

Активность плейлиста по провинциям

В этом отчёте представлена ​​статистика активности плейлистов по штатам США и округу Колумбия. Для этого отчёта необходимо отфильтровать результаты, чтобы получить данные только по Соединённым Штатам.

Места воспроизведения

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

Подробности места воспроизведения (<= 25 результатов)

Примечание: для этого отчёта необходимо задать для параметра maxResults целое значение не более 25 В отличие от большинства других отчётов, для этого отчёта также требуется указать значение параметра запроса sort .

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

Источники трафика

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

Подробная информация об источнике трафика (<= 25 результатов)

Примечание: для этого отчёта необходимо задать для параметра maxResults целое значение не более 25 В отличие от большинства других отчётов, для этого отчёта также требуется указать значение параметра запроса sort .

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

Например, если для фильтра insightTrafficSourceType установить ADVERTISING , в отчете будут перечислены типы рекламы, которые сгенерировали наибольшее количество просмотров или времени просмотра плейлистов канала.

Примечание: этот отчёт поддерживается только для определённых источников трафика. Источники трафика VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED — некоторые из неподдерживаемых.

Тип устройства и операционная система

Тип устройства

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

Операционная система

В этом отчёте собрана статистика просмотров по операционным системам зрителей. Например, он определяет количество просмотров на устройствах Android или PlayStation.

Операционная система и тип устройства

Этот отчёт собирает статистику просмотров по операционным системам и типам устройств пользователей. Например, он показывает, сколько просмотров было совершено на планшетах Android или настольных компьютерах Windows.

Демографические данные зрителей

Лучшие плейлисты

Примечание: для этих отчётов необходимо задать для параметра maxResults целое значение не более 200 До 1 января 2013 года данные доступны только для 10 лучших плейлистов. В отличие от большинства других отчётов, для этих отчётов также требуется указать значение параметра запроса sort .

В этом отчете перечислены лучшие плейлисты канала на основе указанных критериев фильтрации и сортировки.

Отчеты о членстве

Аннулирование членства

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

Отчеты об эффективности рекламы

Примечание: для отчетов об эффективности рекламы требуется токен авторизации, предоставляющий доступ к области https://www.googleapis.com/auth/yt-analytics-monetary.readonly .

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

Показатели эффективности рекламы на основе показов:

• валовой доход
• adImpressions
• cpm

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

• playbackBasedCpm
• монетизированные воспроизведения

Эффективность рекламы по типу рекламы