На этой странице перечислены отчеты, которые владельцы каналов могут получить с помощью API YouTube Analytics. Отчеты о канале предоставляют показатели активности пользователей для определенного канала и измеряют такие показатели, как просмотры видео, рейтинги и количество подписок.
Отчеты о видео предоставляют статистику по всей активности пользователей, связанной с видео канала.
Отчеты о списках воспроизведения предоставляют статистические данные, относящиеся непосредственно к просмотрам видео, происходящим в контексте списка воспроизведения.
Отчеты об эффективности рекламы содержат показатели, связанные с доходом и эффективностью рекламы. Они используют параметр adType для группировки показателей на основе типов рекламы, которая показывалась во время воспроизведения видео. В разделе отчетов об эффективности рекламы описаны два типа показателей эффективности рекламы, которые поддерживает API.
Получение отчета
Чтобы получить отчет о канале, необходимо установить для параметра ids в запросе API одно из следующих значений:
channel==MINE – API возвращает данные для канала YouTube аутентифицированного пользователя.
channel== CHANNEL_ID – установите CHANNEL_ID в уникальный идентификатор канала, для которого вы получаете данные. Пользователь, разрешающий запрос, должен быть владельцем канала.
Идентификатор канала в настоящее время представляет собой строку, начинающуюся с букв UC , хотя ее формат может быть изменен. (Идентификатор вашего канала можно найти на странице расширенных настроек учетной записи вашего канала YouTube, или вы можете получить идентификатор своего канала программно, используя channels.listYouTube Data API's .)
Авторизация
Все запросы API YouTube Analytics должны быть авторизованы. Руководство по авторизации объясняет, как использовать протокол OAuth 2.0 для получения токенов авторизации.
Запросы YouTube Analytics API используют следующие области авторизации:
Просматривайте отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к показателям активности пользователей, таким как количество просмотров и рейтингов.
Просматривайте финансовые отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к показателям активности пользователей, а также к показателям предполагаемого дохода и эффективности рекламы.
https://www.googleapis.com/auth/youtube
Управляйте своим аккаунтом YouTube. В API YouTube Analytics владельцы каналов используют эту область для управления группами и элементами групп YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner
Просматривайте ресурсы YouTube и связанный с ними контент на YouTube и управляйте ими. В API YouTube Analytics владельцы контента используют эту область для управления группами и элементами групп YouTube Analytics.
Примечание. Расчетный доход и показатели эффективности рекламы в настоящее время не поддерживаются в отчетах по каналам. В результате область https://www.googleapis.com/auth/yt-analytics-monetary.readonly в настоящее время не предоставляет доступ к денежным данным в этих отчетах.
Фильтры
В таблицах, описывающих поддерживаемые отчеты, указаны фильтры, которые можно использовать для каждого отчета. В таблицах фильтры, указанные в скобках, не являются обязательными. Например, для параметра фильтрации video(,country)видеофильтр является обязательным, а фильтр страны является необязательным.
API также поддерживает возможность указывать несколько значений для фильтров video и playlist . Если вы укажете несколько значений для одного из этих фильтров, вы также можете добавить этот фильтр в список измерений, указанный для запроса. Это верно, даже если фильтр не указан в качестве поддерживаемого параметра для конкретного отчета.
См. определение параметра filters для получения полного объяснения того, как фильтровать результаты API по определенному значению или набору значений.
Понимание таблиц отчета
В этом разделе объясняются форматирование и терминология, используемые в таблицах, определяющих отчеты, поддерживаемые 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 или более: у вас есть возможность включить любое или все значения из группы.
Видеоотчеты
Основная статистика
Базовая статистика активности пользователей
В этом отчете представлена статистика действий пользователей на канале. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео или страны.
Базовая статистика активности пользователей по штатам США
В этом отчете представлена статистика по конкретному штату США или округу Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
Активность пользователей по странам за определенные периоды времени
В этом отчете представлена статистика действий пользователей на канале за определенные промежутки времени. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео или страны.
Активность пользователей в штатах США за определенные периоды времени
В этом отчете представлена статистика активности пользователей для конкретного штата США или округа Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
В этом отчете представлена статистика активности пользователей канала по каждой стране. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео.
В этом отчете представлена статистика активности пользователей для штатов США и округа Колумбия. Для этого отчета необходимо установить значение параметра filterscountry==US .
Активность пользователей по городам (<= 250 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 250 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете представлена статистика активности пользователей по городам.
В этом отчете представлена статистика активности пользователей по назначенным рыночным областям (DMA). Для этого отчета необходимо либо установить значение параметра filterscountry==US , либо выполнить фильтрацию по определенной провинции (штату США).
Подробные отчеты о воспроизведении содержат статистику, связанную со следующими атрибутами просмотра:
Был ли просмотр прямой видеотрансляции или видео по запросу?
Был ли зритель подписан на канал, которому принадлежит видео?
На каком продукте YouTube произошел просмотр?
Примечание. Измерение и фильтр liveOrOnDemand нельзя использовать вместе с метрикой AverageViewPercentage . Таким образом, в каждом из следующих подразделов перечислены два отчета. Один отчет поддерживает измерение (и фильтр) liveOrOnDemand , а другой — метрику AverageViewPercentage .
Активность пользователей по статусу подписки
В этом отчете представлены показатели активности пользователей для подписавшихся и отписавшихся зрителей. Статистика может быть сгруппирована по периоду времени ( день или месяц ), а также отчет можно отфильтровать по стране , континенту или субконтиненту .
Активность пользователей по статусу подписки для провинций
В этом отчете представлены показатели активности пользователей для подписавшихся и отписавшихся зрителей в штатах США или округе Колумбия. Этот отчет поддерживает меньше показателей, чем предыдущий отчет.
Детали воспроизведения с дополнительным измерением времени
Измерение времени — день или месяц — не является обязательным для этих отчетов, поскольку в любом случае вам необходимо использовать параметры запроса startDate и endDate , чтобы указать диапазон дат, который будет охватывать отчет. Измерение, если оно присутствует, указывает на то, что вы хотите, чтобы данные в отчете были агрегированы по дням, месяцам и т. д.
Детали воспроизведения с дополнительным измерением времени и статистикой liveOrOnDemand .
В этом отчете представлена подробная статистика воспроизведения за определенные интервалы времени. Он поддерживает измерение (и фильтр) liveOrOnDemand .
Следующий отчет аналогичен предыдущему. Он добавляет поддержку метрики AverageViewPercentage , но не поддерживает liveOrOnDemand в качестве измерения или фильтра.
Детали воспроизведения по провинциям со статистикой liveOrOnDemand
В этом отчете представлена подробная статистика воспроизведения для штатов США и округа Колумбия. Он поддерживает измерение (и фильтр) liveOrOnDemand .
Следующий отчет аналогичен предыдущему. Он добавляет поддержку метрики AverageViewPercentage , но не поддерживает liveOrOnDemand в качестве измерения или фильтра.
Подробности о месте воспроизведения (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете указаны встроенные видеопроигрыватели, которые обеспечили наибольшее количество просмотров или времени просмотра видео канала.
В этом отчете собрана статистика просмотров на основе того, каким образом зрители добрались до вашего видеоконтента. Например, он определяет количество просмотров, полученных в результате поиска в Google или по ссылке на похожее видео.
Примечание. Этот отчет возвращает ошибку, если произведение количества запрошенных видео на число дней в диапазоне дат превышает 50 000. Например, запрос, который получает данные для 500 идентификаторов видео, может запрашивать данные максимум за 100 дней. Чтобы уменьшить количество строк, возвращаемых запросом, разделите запрос на несколько запросов, которые указывают меньшее количество видео или устанавливают более короткие диапазоны дат.
Подробности об источнике трафика (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете собрана статистика просмотров на основе источников, которые сгенерировали наибольшее количество просмотров контента канала. Рефереры классифицируются по типу источника трафика, а определение измерения InsightTrafficSourceDetail определяет источники трафика, для которых доступен отчет. Например, если вы установите для фильтра InsightTrafficSourceTypeADVERTISING , в отчете будут перечислены типы рекламы, которые вызвали наибольшее количество просмотров или время просмотра контента канала.
Примечание. Этот отчет поддерживается только для определенных источников трафика. Источники трафика VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED относятся к числу неподдерживаемых.
Тип устройства и операционная система
Тип устройства
В этом отчете собрана статистика просмотров на основе того, каким образом зрители добрались до вашего видеоконтента. Например, он определяет количество просмотров, произошедших на мобильных устройствах или игровых консолях.
В этом отчете собрана статистика просмотров на основе операционных систем зрителей. Например, он определяет количество просмотров, произошедших на устройствах Android или на PlayStation.
В этом отчете собрана статистика просмотров на основе операционных систем и типов устройств зрителей. Например, он определяет количество просмотров, произошедших на планшетах Android или на настольных устройствах Windows.
Например, отчет, в котором используется измерение subscribedStatus , возвращает данныеviewerPercentage, добавляющие до 100 процентов для просмотров, на которые есть подписка , иданныеviewerPercentage, добавляющие до 100 процентов, для просмотров, на которые не подписаны. (Общее значение всех полей viewerpercentage в отчете составляет 200 процентов.)
Вы можете использовать фильтры, чтобы гарантировать, что отчет содержит только данные ViewerPercentage для одного значения (или комбинации значений) для параметров подробностей воспроизведения.
Взаимодействие и обмен контентом
В этом отчете представлена статистика, показывающая, как часто видео канала публиковались на разных социальных платформах.
В этом отчете измеряется способность видео удерживать аудиторию, а также показано, как часто просматривались определенные части видео. Измерение elapsedVideoTimeRatio измеряет количество прошедшего видео для соответствующих значений показателя. Метрики можно разделить на две категории:
Удержание аудитории
Эти показатели показывают, насколько хорошо видео удерживает свою аудиторию.
audienceWatchRatio — это коэффициент, который сравнивает количество просмотров определенной части видео с общим количеством просмотров видео.
relativeRetentionPerformance показывает, насколько хорошо видео удерживает зрителей во время воспроизведения по сравнению с другими видео YouTube аналогичной длины.
Подробная статистика просмотра
Эти показатели предоставляют информацию о том, как часто просматривались определенные части видео.
startedWatching указывает, как часто зрители начинали смотреть видео во время определенного сегмента видео.
stoppedWatching указывает, как часто зрители прекращали просмотр видео во время определенного сегмента видео.
Примечание. Этот отчет не поддерживает возможность указать список значений, разделенных запятыми, для video ; значение должно указывать один идентификатор видео.
В этом отчете показаны одновременные зрители на определенной позиции для одного видео в прямом эфире. Фильтр определяет видео. Размер позиции обычно представляет собой одну минуту.
Примечание. Для этих отчетов необходимо установить для параметра maxResults целое значение 200 или меньше. До 1 января 2013 г. данные доступны только для 10 лучших видео. В отличие от большинства других отчетов, эти отчеты также требуют указания значения параметра запроса sort .
Лучшие видео с дополнительными региональными фильтрами (<= 200 результатов)
В этом отчете перечислены лучшие видео канала. Отчет можно отфильтровать, чтобы получить список лучших видео по стране , континенту или субконтиненту .
В этом отчете перечислены лучшие видео канала в конкретном штате США или округе Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
Лучшие видео для подписавшихся или отписавшихся зрителей (<= 200 результатов)
В этом отчете перечислены лучшие видео канала для подписавшихся или отписавшихся зрителей. Отчет можно отфильтровать, чтобы получить список лучших видео по стране , континенту или субконтиненту . Предыдущий отчет позволяет получить самые популярные видео в определенном штате США для подписавшихся или отписавшихся зрителей, но он поддерживает меньше показателей, чем этот отчет.
Лучшие видео по продуктам YouTube (<= 200 результатов)
В этом отчете перечислены самые популярные видео канала, а также поддерживаются подробные сведения о воспроизведении и географические фильтры. Этот отчет похож на предыдущий, но поддерживает меньше показателей и добавляет поддержку фильтра youtubeProduct .
Отчеты о плейлистах содержат показатели, связанные с активностью пользователей, связанной с видео в плейлистах владельца канала. Доступны две версии этих отчетов, и для каждого доступного отчета следующие разделы содержат описание каждой версии:
На вкладке «Рекомендовано» в каждом разделе описан предпочтительный формат запроса API для получения соответствующего отчета. Рекомендуемые отчеты поддерживают расширенный набор показателей, включающий как совокупные показатели видео , так и показатели плейлиста . Этот формат запроса не использует измерение isCurated .
На вкладке «Использование isCurated в каждом разделе описан более старый формат запроса API, в котором требуется измерение isCurated . Эти отчеты поддерживают только показатели плейлиста . Обратите внимание, что параметр isCurated устарел для всех отчетов. В примечании ниже поясняется график прекращения поддержки.
В следующем примечании к предупреждению более подробно объясняются различия между двумя версиями отчета.
Совокупные показатели видео
Эти метрики предоставляют показатели активности пользователей и показов, которые суммируются для всех видео в плейлисте, которые также принадлежат каналу, которому принадлежит плейлист. Показатели видео, принадлежащих другим каналам, при агрегировании не рассчитываются. В результате, если канал создает плейлист, содержащий только видео, принадлежащие другим каналам, в отчетах по этим плейлистам не будут указаны значения этих показателей.
Эти показатели отражают активность и вовлеченность пользователей в контексте страницы плейлиста. Эти показатели включают просмотры всех видео в плейлисте, независимо от того, какому каналу они принадлежат, но учитываются только просмотры, произошедшие в контексте плейлиста.
В этом отчете представлена статистика взаимодействия пользователей с видео в плейлистах канала. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного списка воспроизведения.
В этом отчете представлена статистика взаимодействия пользователей с видео в плейлистах канала. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного списка воспроизведения.
В этом отчете представлена статистика активности плейлистов для штатов США и округа Колумбия. Для этого отчета необходимо отфильтровать результаты, чтобы получить данные только для США.
Подробности о месте воспроизведения (<= 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.
Примечание. Значения ViewerPercentage в этом отчете не нормализованы для различных значений параметра подробностей воспроизведения subscribedStatus .
Например, отчет, в котором используется измерение subscribedStatus , возвращает данныеviewerPercentage, добавляющие до 100 процентов для просмотров, на которые есть подписка , иданныеviewerPercentage, добавляющие до 100 процентов, для просмотров, на которые не подписаны. (Общее значение всех полей viewerpercentage в отчете составляет 200 процентов.)
Примечание. Для этих отчетов необходимо установить для параметра maxResults целое значение 200 или меньше. До 1 января 2013 года данные доступны только для 10 лучших плейлистов. В отличие от большинства других отчетов, эти отчеты также требуют указания значения параметра запроса sort .
В этом отчете перечислены лучшие плейлисты канала на основе указанных критериев фильтрации и сортировки.
Примечание. Для отчетов об эффективности рекламы требуется токен авторизации, который предоставляет доступ к области https://www.googleapis.com/auth/yt-analytics-monetary.readonly .
В отчетах об эффективности рекламы представлены показатели показов объявлений, которые показывались во время воспроизведения видео. Эти показатели учитывают каждый показ рекламы, и каждое воспроизведение видео может привести к нескольким показам.
Показатели эффективности рекламы на основе показов:
Кроме того, некоторые отчеты по видео поддерживают следующие показатели эффективности рекламы на основе воспроизведения. Однако эти показатели не включаются в отчеты об эффективности рекламы.
