YouTube Analytics API: Content Owner Reports

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

На этой странице перечислены отчеты, которые владельцы контента могут получить с помощью YouTube Analytics API. Отчеты о владельцах контента содержат показатели для каналов, связанных с указанным владельцем контента 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 , параметр isCurated , либо поддерживаемую комбинацию claimedStatus и uploaderType . (Поддерживаемые комбинации перечислены в определении измерения uploaderType .)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этом отчете собрана статистика просмотров на основе того, как зрители добрались до вашего видеоконтента. Например, он определяет количество просмотров, полученных в результате поиска 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 . Отчет также поддерживает фильтрацию по регионам.

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

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

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

по времени

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

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

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

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

В этом отчете представлена ​​статистика активности плейлистов для штатов США и округа Колумбия. Для этого отчета вы включаете 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
• монетизированныевоспроизведения

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