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. В приведенной ниже таблице перечислены параметры, показатели и фильтры, поддерживаемые для отчетов о плейлистах каналов с временной привязкой:

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

• dimensions=day
• dimensions=7DayTotals,subscribedStatus
• dimensions=30DayTotals,subscribedStatus,youtubeProduct
• dimensions=month,youtubeProduct

Однако значение параметра day,month недопустимо, так как оно использует два измерения на основе времени, но запрос должен использовать ровно 1. В этом случае значение параметра subscribedStatus,youtubeProduct фактически возвращает отчет, но показатели не агрегируются по дням. , неделя, месяц и т. д. (Этот отчет документируется отдельно в документации.)

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

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

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

Видео отчеты

Основные характеристики

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

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

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

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

по времени

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание. Измерение и фильтр liveOrOnDemand нельзя использовать вместе с метрикой AverageViewPercentage . Таким образом, в каждом из следующих подразделов перечислены два отчета. Один отчет поддерживает измерение (и фильтр) liveOrOnDemand , а другой — метрику AverageViewPercentage .

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

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

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

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

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

Измерение времени — день или месяц — является необязательным для этих отчетов, поскольку в любом случае вам необходимо использовать параметры запроса startDate и endDate , чтобы указать диапазон дат, который будет охватывать отчет. Измерение, если оно присутствует, указывает, что вы хотите, чтобы данные в отчете были агрегированы по дням, месяцам и т. д.

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

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

Детали воспроизведения с необязательным параметром времени и метрикой AverageViewPercentage

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

Детали воспроизведения по странам

Детали воспроизведения по странам со статистикой liveOrOnDemand

В этом отчете представлена ​​подробная статистика воспроизведения по странам. Он поддерживает измерение liveOrOnDemand (и фильтр).

Детали воспроизведения по странам с метрикой mediumViewPercentage

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

Детали воспроизведения по провинциям

Детали воспроизведения по провинциям со статистикой liveOrOnDemand

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

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

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

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

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

Этот отчет предоставляет статистику, относящуюся к типу страницы или приложения, где произошло воспроизведение видео.

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

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

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

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

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

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

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

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

В этом отчете собрана статистика просмотров на основе рефереров, сгенерировавших наибольшее количество просмотров контента канала. Источники перехода классифицируются по типу источника трафика, а определение измерения InsightTrafficSourceDetail определяет источники трафика, для которых доступен отчет. Например, если вы установите для фильтра InsightTrafficSourceType значение ADVERTISING , в отчете будут перечислены типы объявлений, которые вызвали наибольшее количество просмотров или времени просмотра контента канала.

Примечание. Этот отчет поддерживается только для определенных источников трафика. Например, источник трафика NO_LINK_EMBEDDED не имеет дополнительных деталей и, следовательно, не поддерживает этот отчет. Подробные сведения о том, какие источники трафика поддерживают этот отчет, см. в определении insightTrafficSourceType .

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

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

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

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

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

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

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

Демография зрителей

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

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

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

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

Этот отчет измеряет способность видео удерживать свою аудиторию. Измерение elapsedVideoTimeRatio измеряет количество истекшего видео для соответствующих значений метрик. Метрики audienceWatchRatio и relativeRetentionPerformance предоставляют два измерения, которые показывают, насколько хорошо видео удерживает свою аудиторию. Первое является абсолютным значением, а второе показывает, как видео работает по сравнению с другими видео YouTube аналогичной длины.

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

Лучшие видео

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

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

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

Популярные видео по штатам (<= 200 результатов)

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

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

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

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

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

Популярные видео с фильтрами сведений о воспроизведении (<= 200 результатов)

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

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

Основные характеристики

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

по времени

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

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

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

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

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

В этом отчете представлена ​​статистика активности плейлистов для штатов США и округа Колумбия. Для этого отчета вы включаете country==US в значение параметра filters .

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

Этот отчет предоставляет статистику, относящуюся к типу страницы или приложения, в котором произошло воспроизведение плейлиста.

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

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

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

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

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

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

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

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

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

Примечание. Этот отчет поддерживается только для определенных источников трафика. Например, источник трафика NO_LINK_EMBEDDED не имеет дополнительных деталей и, следовательно, не поддерживает этот отчет. Подробные сведения о том, какие источники трафика поддерживают этот отчет, см. в определении insightTrafficSourceType .

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

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

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

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

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

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

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

Демография зрителей

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

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

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

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

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

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

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

• валовой доход
• показы рекламы
• цена за тысячу показов

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

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

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