YouTube Analytics API: Content Owner Reports

Примечание: Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program .

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

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

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

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

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

Чтобы получить отчёт о владельце контента, вызовите метод API reports.query и задайте для параметра ids в запросе API значение contentOwner== OWNER_NAME , где OWNER_NAME — идентификатор владельца контента. Если вы не уверены в значении, обратитесь к своему менеджеру по работе с партнёрами.

Авторизация

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

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

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

Фильтры

Все запросы API для получения отчетов о владельцах контента должны фильтровать данные, используя либо измерение video , либо измерение channel , либо поддерживаемую комбинацию измерений claimedStatus и uploaderType . (Поддерживаемые комбинации перечислены в определении измерения uploaderType .)

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

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

Полное объяснение того, как фильтровать результаты 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 .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этом отчёте определяются встроенные видеоплееры, которые сгенерировали наибольшее количество просмотров или времени просмотра контента владельца контента. При получении этого отчёта необходимо установить фильтр insightPlaybackLocationType на EMBEDDED .

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

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

Этот отчёт собирает статистику просмотров на основе способов, которыми зрители получили доступ к вашему видеоконтенту. Например, он определяет количество просмотров, полученных через поиск 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 аналогичной длительности.

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

Лучшие видео

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Подробности места воспроизведения (<= 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
• монетизированные воспроизведения

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