Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
На этой странице перечислены отчеты, которые владельцы каналов могут получить с помощью 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 или по ссылке на похожее видео.
Подробности об источнике трафика (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете собрана статистика просмотров на основе источников, которые сгенерировали наибольшее количество просмотров контента канала. Рефереры классифицируются по типу источника трафика, а определение измерения InsightTrafficSourceDetail определяет источники трафика, для которых доступен отчет. Например, если вы установите для фильтра InsightTrafficSourceType значение ADVERTISING , в отчете будут перечислены типы рекламы, которые вызвали наибольшее количество просмотров или время просмотра контента канала.
Примечание. Этот отчет поддерживается только для определенных источников трафика. Источники трафика 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 .
В отчетах об эффективности рекламы представлены показатели показов объявлений, которые показывались во время воспроизведения видео. Эти показатели учитывают каждый показ рекламы, и каждое воспроизведение видео может привести к нескольким показам.
Показатели эффективности рекламы на основе показов:
Кроме того, некоторые отчеты по видео поддерживают следующие показатели эффективности рекламы на основе воспроизведения. Однако эти показатели не включаются в отчеты об эффективности рекламы.
На этой странице перечислены отчеты, которые владельцы каналов могут получить с помощью 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 и элементами групп.
Примечание. Расчетные показатели доходов и производительности рекламы в настоящее время не поддерживаются для отчетов о каналах. В результате https://www.googleapis.com/auth/yt-analytics-monetary.readonly Scope в настоящее время не предоставляет доступ к денежным данным в этих отчетах.
Фильтры
Таблицы, которые объясняют поддерживаемые отчеты, определяют фильтры, которые можно использовать для каждого отчета. В таблицах фильтры, показанные в скобках, являются необязательными. Например, для video(,country) требуется видеофильтр , и фильтр страны не является обязательным.
API также поддерживает возможность указать несколько значений для фильтров video и playlist . Если вы указываете несколько значений для одного из этих фильтров, вы также можете добавить этот фильтр в список измерений, которые вы указываете для запроса. Это верно, даже если фильтр не указан в качестве поддерживаемого измерения для конкретного отчета.
См. Определение параметра filters для полного объяснения того, как фильтровать результаты API для определенного значения или набора значений.
Понимание таблиц отчетов
В этом разделе объясняется форматирование и терминология, используемая в таблицах, которые определяют сообщения, которые поддерживает API. В следующей таблице перечислены размеры, метрики и фильтры, поддерживаемые для видео отчета о воспроизведении, используя размер времени и метрику среднего значения .
Таблица содержит два ряда для размеров, одна строка для метрик и три ряда для фильтров. Для измерений и фильтров значения из каждой строки могут быть объединены в запросе 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). Для этого отчета вы должны либо установить значение параметра filters в country==US , либо фильтр в конкретную провинцию (штат США).
Отчеты о деталях воспроизведения предоставляют статистику, связанную со следующими атрибутами просмотра:
Было ли представление о трансляции в прямом эфире или видео по требованию?
Был ли зритель подписан на канал, которому принадлежит видео?
На каком продукте YouTube произошел вид?
ПРИМЕЧАНИЕ. Использование и фильтр Liveorondemand нельзя использовать в сочетании с метрикой среднего показателя . Таким образом, в каждом из следующих подраздела перечислены два отчета. В одном отчете поддерживается размерное измерение (и фильтр) LiveOrondemand , в то время как другой поддерживает метрику среднего значения .
Активность пользователя подписанным статусом
В этом отчете представлены показатели активности пользователей для подписанных и отписанных зрителей. Статистика может быть сгруппирована по периоду времени ( день или месяц ), а отчет также может быть отфильтрован по стране , континенту или субконтиненту .
Активность пользователя подписанным статусом для провинций
В этом отчете представлены показатели активности пользователей для подписанных и отписанных зрителей в штатах США или в округе Колумбия. Этот отчет поддерживает меньше показателей, чем в предыдущем отчете.
Детали воспроизведения с необязательным измерением времени
Размер времени - день или месяц - является необязательным для этих отчетов, потому что, несмотря на это, вам необходимо использовать параметры запроса startDate и endDate чтобы указать диапазон дат, который будет охватывать отчет. Измерение, если присутствует, указывает на то, что вы хотите, чтобы данные в отчете были агрегированы днем, месяцем и т. Д.
Детали воспроизведения с необязательным измерением времени и статистикой Liveorondemand
В этом отчете содержится статистика деталей воспроизведения для определенных временных интервалов. Он поддерживает измерение Liveorondemand (и фильтр).
Следующий отчет похож на предыдущий. Он добавляет поддержку метрики среднего VistperCentage , но не поддерживает LiveorOndemand как измерение или фильтр.
Следующий отчет похож на предыдущий. Он добавляет поддержку метрики среднего VistperCentage , но не поддерживает LiveorOndemand как измерение или фильтр.
Подробная информация о местоположении воспроизведения (<= 25 результатов)
Примечание. Этот отчет требует, чтобы вы установили параметр maxResults на целочисленное значение 25 или менее. В отличие от большинства других отчетов, этот отчет также требует, чтобы вы указали значение для параметра запроса sort .
В этом отчете определяются встроенные видеопроглетики, которые генерировали наибольшее количество просмотров или просмотра времени для видео канала.
В этом отчете агрегирует просмотр статистики на основе того, как зрители достигли вашего видеоконтента. Например, он идентифицирует количество представлений, которые связаны с поиском Google или по ссылке на связанное видео.
Примечание. Этот отчет требует, чтобы вы установили параметр maxResults на целочисленное значение 25 или менее. В отличие от большинства других отчетов, этот отчет также требует, чтобы вы указали значение для параметра запроса sort .
В этом отчете агрегирует просмотр статистики на основе реферателей, которые генерировали наибольшее количество представлений для содержания канала. Рефераторы классифицируются по типу источника трафика, а определение Dimension InsightTrafficsUceCedetail определяет источники трафика, для которых доступен отчет. Например, если вы установите фильтр insighttrafficsourcetype для ADVERTISING , в отчете будут перечислены типы рекламы, которые генерировали наибольшее количество просмотров или время просмотра контента канала.
Примечание. Этот отчет поддерживается только для конкретных источников трафика. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED Источники трафика являются одними из неподдерживаемых.
Тип устройства и операционная система
Тип устройства
В этом отчете агрегирует просмотр статистики на основе того, как зрители достигли вашего видеоконтента. Например, он идентифицирует количество просмотров, которые произошли на мобильных устройствах или игровых приставках.
Этот отчет объединяет просмотр статистики на основе операционных систем зрителей. Например, он определяет количество просмотров, которые произошли на устройствах Android или на Playstations.
В этом отчете агрегирует просмотр статистики на основе операционных систем зрителей и типов устройств. Например, он идентифицирует количество просмотров, которые произошли на планшетах Android или на настольных устройствах Windows.
Например, в отчете, в котором используется Dimension, возвращает данные ViewErperPercentage, добавляя до 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 Tab в каждом разделе описывает более старый формат запроса API, в котором требуется isCurated измерение. Эти отчеты поддерживают только метрики в игре . Обратите внимание, что isCurated измерение установилось для всех отчетов. Примечание в предупреждении объясняет график снижения.
В следующем предупреждении примечание объясняет изменения между двумя версиями отчета более подробно.
Агрегированные видео -метрики
Эти показатели предоставляют пользовательские показатели и впечатления, которые агрегированы для всех видео в списке воспроизведения, которые также принадлежат каналу, которому принадлежит плейлист. Метрики для видео, принадлежащих другим каналам, не вычисляются в агрегации. В результате, если канал создает список воспроизведения, который содержит только видео, принадлежащие другими каналами, отчеты для этих плейлистов не будут предоставлять ценности для этих показателей.
Эти метрики отражают активность пользователя и вовлечение в контексте страницы плейлиста. Эти показатели включают в себя представления для всех видео в списке воспроизведения, независимо от того, каким каналом они владеют, но считают только представления, которые произошли в контексте плейлиста.
В этом отчете представлена статистика, связанная с взаимодействием пользователей с видео в списках воспроизведения канала. Вы можете отфильтровать отчет, чтобы вернуть данные только для конкретного плейлиста.
В этом отчете представлена статистика, связанная с взаимодействием пользователей с видео в списках воспроизведения канала. Вы можете отфильтровать отчет, чтобы вернуть данные только для конкретного плейлиста.
В этом отчете представлена статистика, связанная с взаимодействиями, которые пользователи в определенной стране имеют с видео в списках воспроизведения канала.
В этом отчете содержится статистика деятельности плейлиста для штатов США и округа Колумбия. Для этого отчета вы должны отфильтровать результаты, чтобы вернуть данные только для Соединенных Штатов.
В этом отчете содержится статистика, связанная с типом страницы или приложения, где произошли воспроизведения видеороликов вашего списка воспроизведения.
Подробная информация о местоположении воспроизведения (<= 25 результатов)
Примечание. Этот отчет требует, чтобы вы установили параметр maxResults на целочисленное значение 25 или менее. В отличие от большинства других отчетов, этот отчет также требует, чтобы вы указали значение для параметра запроса sort .
В этом отчете определяется встроенные видеопроглетики, которые генерировали наибольшее количество просмотров или просмотра времени для видео в списках воспроизведения канала.
Этот отчет объединяет статистику просмотра на основе того, как зрители достигли контента вашего списка воспроизведения. Например, он идентифицирует количество представлений, которые связаны с поиском Google.
Примечание. Этот отчет требует, чтобы вы установили параметр maxResults на целочисленное значение 25 или менее. В отличие от большинства других отчетов, этот отчет также требует, чтобы вы указали значение для параметра запроса sort .
В этом отчете агрегирует просмотр статистики на основе реферателей, которые генерировали наибольшее количество представлений для видео в списках воспроизведения канала. Рефераторы классифицируются по типу источника трафика, а определение Dimension InsightTrafficsUceCedetail определяет источники трафика, для которых доступен отчет.
Например, если вы установите фильтр insighttrafficsourcetype для ADVERTISING , в отчете будут перечислены типы рекламы, которые генерировали большинство просмотров или времени просмотра для плейлистов канала.
Примечание. Этот отчет поддерживается только для конкретных источников трафика. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED Источники трафика являются одними из неподдерживаемых.
Тип устройства и операционная система
Тип устройства
В этом отчете агрегирует просмотр статистики на основе того, как зрители достигли видео в ваших списках воспроизведения. Например, он идентифицирует количество просмотров, которые произошли на мобильных устройствах или игровых приставках.
Этот отчет объединяет просмотр статистики на основе операционных систем зрителей. Например, он определяет количество просмотров, которые произошли на устройствах Android или на Playstations.
В этом отчете агрегирует просмотр статистики на основе операционных систем зрителей и типов устройств. Например, он определяет, сколько просмотров произошло на планшетах Android или настольных устройствах Windows.
ПРИМЕЧАНИЕ. Значения ViewerPerCentage в этом отчете не нормализованы для различных значений измерения детализации воспроизведения подписания .
Например, в отчете, в котором используется Dimension, возвращает данные ViewErperPercentage, добавляя до 100 процентов для подписанных представлений и данных ViewerPerCentage , что составляет до 100 процентов для отписных представлений. (Общая стоимость всех полей ViewerPerCentage в отчете составляет 200 процентов.)
Вы можете использовать фильтры, чтобы убедиться, что отчет содержит только данные ViewerPercentage для одного значения аспектов подписания .
Лучшие плейлисты
Примечание. Эти отчеты требуют, чтобы вы установили параметр maxResults на целочисленное значение 200 или менее. До 1 января 2013 г. данные доступны только для 10 лучших списков воспроизведения. В отличие от большинства других отчетов, эти отчеты также требуют, чтобы вы указали значение для параметра запроса sort .
В этом отчете перечислены лучшие плейлисты канала на основе указанных критериев фильтрации и сортировки.
ПРИМЕЧАНИЕ. Отчеты о производительности рекламы требуют токена авторизации, который предоставляет доступ к https://www.googleapis.com/auth/yt-analytics-monetary.readonly Scope.
Отчеты AD Performance предоставляют показатели, основанные на впечатлениях, для рекламы, которые работали во время воспроизведения видео. Эти метрики учитывают каждое впечатление от рекламы, и каждое воспроизведение видео может дать несколько впечатлений.
На основе впечатлений показатели производительности рекламы:
Кроме того, некоторые видео отчеты поддерживают следующие показатели производительности рекламы на основе воспроизведения. Тем не менее, эти метрики не включены в отчеты о производительности рекламы.
На этой странице перечислены отчеты, которые владельцы каналов могут получить с помощью API YouTube Analytics. Отчеты о каналах предоставляют метрики активности пользователей для указанного канала и измеряют такие вещи, как просмотры видео, рейтинги и количество подписки.
Видео -отчеты предоставляют статистику для всей деятельности пользователей, связанных с видео канала.
Отчеты плейлиста предоставляют статистику, которая специально связана с просмоткой видео, которые встречаются в контексте плейлиста.
Отчеты о производительности рекламы содержат показатели, связанные с доходами и производительностью рекламы. Они используют измерение adtype для групповых метрик на основе типов рекламы, которые работали во время воспроизведения видео. В разделе «Отчеты об рекламе» объясняются два типа показателей производительности рекламы, которые поддерживает API.
Получение отчета
Чтобы получить отчет о канале, вы должны установить значение параметра ids в вашем запросе API на одно из следующих значений:
channel==MINE - API возвращает данные для аутентифицированного пользователя канала YouTube.
channel== CHANNEL_ID - SET CHANNEL_ID на уникальный идентификатор канала канала, для которого вы получаете данные. Пользователь, разрешающий запрос, должен быть владельцем канала.
Идентификатор канала в настоящее время является строкой, которая начинается с букв UC , хотя его формат может быть изменен. (Вы можете найти идентификатор вашего канала на странице «Настройки расширенной учетной записи» для вашего канала YouTube, или вы можете программно получить идентификатор канала channels.list используя метод YouTube Data API's .)
Авторизация
Все запросы на API API YouTube должны быть разрешены. Руководство по авторизации объясняет, как использовать протокол OAuth 2.0 для получения токенов авторизации.
Запросы API youtube Analytics Используйте следующие аспекты авторизации:
Посмотреть отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к показателям активности пользователей, например, количество просмотров и количество рейтингов.
Посмотреть монетарные отчеты YouTube Analytics для вашего контента YouTube. Эта область обеспечивает доступ к метрикам активности пользователей, а также к предполагаемым показателям доходов и производительности рекламы.
https://www.googleapis.com/auth/youtube
Управляйте своей учетной записью YouTube. В API API YouTube Analytics владельцы каналов используют эту область для управления группами аналитики YouTube и групп.
https://www.googleapis.com/auth/youtubepartner
Просмотреть и управлять активами YouTube и связанного контента на YouTube. В API YouTube Analytics владельцы контента используют эту область для управления группами аналитики YouTube и элементами групп.
Примечание. Расчетные показатели доходов и производительности рекламы в настоящее время не поддерживаются для отчетов о каналах. В результате https://www.googleapis.com/auth/yt-analytics-monetary.readonly Scope в настоящее время не предоставляет доступ к денежным данным в этих отчетах.
Фильтры
Таблицы, которые объясняют поддерживаемые отчеты, определяют фильтры, которые можно использовать для каждого отчета. В таблицах фильтры, показанные в скобках, являются необязательными. Например, для video(,country) требуется видеофильтр , и фильтр страны не является обязательным.
API также поддерживает возможность указать несколько значений для фильтров video и playlist . Если вы указываете несколько значений для одного из этих фильтров, вы также можете добавить этот фильтр в список измерений, которые вы указываете для запроса. Это верно, даже если фильтр не указан в качестве поддерживаемого измерения для конкретного отчета.
См. Определение параметра filters для полного объяснения того, как фильтровать результаты API для определенного значения или набора значений.
Понимание таблиц отчетов
В этом разделе объясняется форматирование и терминология, используемая в таблицах, которые определяют сообщения, которые поддерживает API. В следующей таблице перечислены размеры, метрики и фильтры, поддерживаемые для видео отчета о воспроизведении, используя размер времени и метрику среднего значения .
Таблица содержит два ряда для размеров, одна строка для метрик и три ряда для фильтров. Для измерений и фильтров значения из каждой строки могут быть объединены в запросе API, пока комбинация следует правилам использования в таблице. Так, например, допустимые значения параметров dimensions для этого отчета включают:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
Тем не менее, day,month недействителен, поскольку он использует два измерения на основе времени, а запрос должен использовать либо 0, либо 1.
Отчет о терминологии таблицы
Таблицы используют следующую терминологию, чтобы указать, требуются ли измерения или необязательно:
Эти термины означают, что значение требуется:
Требуется: вы должны включить значение.
Используйте ровно 1: вы должны включить одно значение из группы.
Use 1 or more: You can include any or all values from the group, but you must include at least one.
These terms mean a value is optional:
Optional: You have the option of include the value.
Use 0 or 1: You have the option of including one value from the group.
Use 0 or more: You have the option of including any or all values from the group.
Video reports
Basic stats
Basic user activity statistics
This report provides statistics related to users' actions on a channel. You can filter the report to only return data for a specific video or country.
This report provides statistics for a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
User activity by country for specific time periods
This report provides statistics related to user actions on a channel for specific time intervals. You can filter the report to only return data for a specific video or country.
User activity in US states for specific time periods
This report provides statistics related to user activity for a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
This report provides statistics related to user activity on a country-by-country basis for a channel. You can filter the report to only return data for a specific video.
This report provides user activity statistics for US states and the District of Columbia. For this report, you must set the filters parameter value to country==US .
Note: This report requires you to set the maxResults parameter to an integer value of 250 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report provides user activity statistics by city.
This report provides user activity statistics by Designated Market Area (DMA). For this report, you must either set the filters parameter value to country==US or filter to a particular province (US state).
Playback detail reports provide statistics related to the following viewing attributes:
Was the view of a live video broadcast or an on-demand video?
Was the viewer subscribed to the channel that owns the video?
On which YouTube product did the view occur?
Note: The liveOrOnDemand dimension and filter cannot be used in conjunction with the averageViewPercentage metric. As such, each of the following subsections lists two reports. One report supports the liveOrOnDemand dimension (and filter), while the other supports the averageViewPercentage metric.
User activity by subscribed status
This report provides user activity metrics for subscribed and unsubscribed viewers. Statistics can be grouped by time period ( day or month ), and the report can also be filtered by country , continent , or subContinent .
This report provides user activity metrics for subscribed and unsubscribed viewers in US states or the District of Columbia. This report supports fewer metrics than the previous report.
The time dimension – day or month – is optional for these reports because, regardless, you need to use the startDate and endDate request parameters to specify the date range that the report will cover. The dimension, if present, indicates that you want data in the report to be aggregated by day, month, etc.
Playback details with optional time dimension and liveOrOnDemand statistics
This report provides playback detail statistics for specific time intervals. It supports the liveOrOnDemand dimension (and filter).
The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.
The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.
Note: This report requires you to set the maxResults parameter to an integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report identifies the embedded video players that generated the most views or viewing time for a channel's videos.
This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that stemmed from a Google search or from a link to a related video.
Note: This report requires you to set the maxResults parameter to an integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report aggregates viewing statistics based on the referrers that generated the most views for the channel's content. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available. For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the channel's content.
Note: This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.
Device type and operating system
Device type
This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that occurred on mobile devices or game consoles.
This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.
This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of views that occurred on Android tablets or on Windows desktop devices.
For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views andviewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)
You can use filters to ensure that the report only contains viewerPercentage data for one value (or combination of values) for playback detail dimensions.
Engagement and content sharing
This report provides statistics showing how frequently the channel's videos were shared on different social platforms.
This report measures a video's ability to retain its audience and also shows how often specific parts of a video were watched. The elapsedVideoTimeRatio dimension measures the amount of the video that has elapsed for the corresponding metric values. The metrics can be broken down into two categories:
Audience retention
These metrics show how well the video retains its audience.
audienceWatchRatio is a ratio that compares the number of times a portion of a video has been watched to the total number of views of the video.
relativeRetentionPerformance shows how well a video retains viewers during playbacks relative to other YouTube videos of a similar length.
Granular watch statistics
These metrics provide information about how often specific parts of a video were watched.
startedWatching indicates how often viewers started watching a video during a particular segment of the video.
stoppedWatching indicates how often viewers stopped watching a video during a particular segment of the video.
Note: This report does not support the ability to specify a comma-separated list of values for the video filter; the value must specify a single video ID.
This report shows the concurrent viewers at a given position for a single live-streamed video. The filter specifies the video. The position dimension generally represents a single minute.
Note: These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 videos. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.
Top videos with optional regional filters (<= 200 results)
This report lists the channel's top videos. The report can be filtered to list top videos by country , continent , or subContinent .
This report lists the channel's top videos in a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
Top videos for subscribed or unsubscribed viewers (<= 200 results)
This report lists the channel's top videos for subscribed or unsubscribed viewers. The report can be filtered to list top videos by country , continent , or subContinent . The previous report lets you retrieve the top videos in a particular US state for subscribed or unsubscribed viewers, but it supports fewer metrics than this report.
This report lists the channel's top videos and supports playback detail and geographic filters. This report is similar to the previous one, but it supports fewer metrics and adds support for the youtubeProduct filter.
Playlist reports contain metrics related to user activity related to videos in the channel owner's playlists. Two versions of these reports are available, and, for each available report, the following sections contain a description of each version:
The Recommended tab in each section describes the preferred API request format for retrieving the corresponding report. The recommended reports support an expanded set of metrics that includes both aggregated video metrics and in-playlist metrics . This request format does not use the isCurated dimension.
The Using isCurated tab in each section describes an older API request format in which the isCurated dimension is required. These reports support in-playlist metrics only. Note that the isCurated dimension has been deprecated for all reports. The warning note below explains the deprecation schedule.
The following warning note explains changes between the two report versions in more detail.
Aggregated video metrics
These metrics provide user activity and impression metrics that are aggregated for all videos in the playlist that are also owned by the channel that owns the playlist. Metrics for videos owned by other channels are not computed in the aggregation. As a result, if a channel creates a playlist that contains only videos owned by other channels, reports for those playlists will not provide values for these metrics.
See the supported playlist metrics section for a list of aggregated video metrics that YouTube supports.
In-playlist metrics
These metrics reflect user activity and engagement in the context of the playlist page. These metrics include views for all videos in the playlist, regardless of which channel owns them, but only counts views that occurred in the playlist context.
This report provides statistics related to users' interactions with the videos in the channel's playlists. You can filter the report to only return data for a specific playlist.
This report provides statistics related to users' interactions with the videos in the channel's playlists. You can filter the report to only return data for a specific playlist.
This report provides playlist activity statistics for US states and the District of Columbia. For this report, you must filter results to return data only for the United States.
Note: This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report identifies the embedded video players that generated the most views or viewing time for the videos in the channel's playlists.
This report aggregates viewing statistics based on how viewers reached your playlist content. For example, it identifies the number of views that stemmed from a Google search.
Note: This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report aggregates viewing statistics based on the referrers that generated the most views for the videos in the channel's playlists. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available.
For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the channel's playlists.
Note: This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.
Device type and operating system
Device type
This report aggregates viewing statistics based on how viewers reached the videos in your playlists. For example, it identifies the number of views that occurred on mobile devices or game consoles.
This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.
This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies how many views occurred on Android tablets or Windows desktop devices.
Note: The viewerPercentage values in this report are not normalized for different values of the subscribedStatus playback detail dimension.
For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views andviewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)
You can use filters to ensure that the report only contains viewerPercentage data for one value of the subscribedStatus dimensions.
Top playlists
Note: These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 playlists. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.
This report lists the channel's top playlists based on the specified filtering and sorting criteria.
Note: Ad performance reports require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.
Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions.
In addition, some video reports support the following playback-based ad performance metrics. However, these metrics are not included in ad performance reports.
This page lists reports that channel owners can retrieve with the YouTube Analytics API. Channel reports provide user activity metrics for a specified channel and measure things like video views, ratings, and subscription counts.
Video reports provide statistics for all user activity related to a channel's videos.
Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist.
Ad performance reports contain metrics related to revenue and ad performance. They use the adType dimension to group metrics based on the types of ads that ran during video playbacks. The ad performance reports section explains the two types of ad performance metrics that the API supports.
Retrieving a report
To retrieve a channel report, you must set the ids parameter value in your API request to one of the following values:
channel==MINE – The API returns data for the authenticated user's YouTube channel.
channel== CHANNEL_ID – Set CHANNEL_ID to the unique channel ID of the channel for which you are retrieving data. The user authorizing the request must be the owner of the channel.
The channel ID is currently a string that begins with the letters UC , though its format is subject to change. (You can find your channel's ID on the advanced account settings page for your YouTube channel, or you can retrieve your channel's ID programmatically using the YouTube Data API'schannels.list method.)
Авторизация
All YouTube Analytics API requests must be authorized. The Authorization guide explains how to use the OAuth 2.0 protocol to retrieve authorization tokens.
YouTube Analytics API requests use the following authorization scopes:
View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics.
https://www.googleapis.com/auth/youtube
Manage your YouTube account. In the YouTube Analytics API, channel owners use this scope to manage YouTube Analytics groups and group items.
https://www.googleapis.com/auth/youtubepartner
View and manage YouTube assets and associated content on YouTube. In the YouTube Analytics API, content owners use this scope to manage YouTube Analytics groups and group items.
Note: Estimated revenue and ad performance metrics are not currently supported for channel reports. As a result, the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope does not currently grant access to monetary data in those reports.
Фильтры
The tables that explain the supported reports identify the filters that can be used for each report. In the tables, filters shown in parentheses are optional. For example, for the filtering option video(,country) , the video filter is required, and the country filter is optional.
The API also supports the ability to specify multiple values for the video and playlist filters. If you do specify multiple values for one of these filters, you can also add that filter to the list of dimensions that you specify for the request. This is true even if the filter is not listed as a supported dimension for a particular report.
See the filters parameter definition for a complete explanation of how to filter API results for a specific value or set of values.
Understanding report tables
This section explains the formatting and terminology used in the tables that define reports that the API supports. The following table lists the dimensions, metrics, and filters supported for the playback details video report using the time dimension and the averageViewPercentage metric.
The table contains two rows for dimensions, one row for metrics, and three rows for filters. For dimensions and filters, values from each row can be combined in an API request as long as the combination follows the usage rules in the table. So, for example, valid dimensions parameter values for this report include:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
However, the parameter value day,month is invalid because it uses two time-based dimensions, and the request must use either 0 or 1.
Report table terminology
Tables use the following terminology to indicate whether dimensions are required or optional:
These terms mean a value is required:
Required: You must include the value.
Use exactly 1: You must include one value from the group.
Use 1 or more: You can include any or all values from the group, but you must include at least one.
These terms mean a value is optional:
Optional: You have the option of include the value.
Use 0 or 1: You have the option of including one value from the group.
Use 0 or more: You have the option of including any or all values from the group.
Video reports
Basic stats
Basic user activity statistics
This report provides statistics related to users' actions on a channel. You can filter the report to only return data for a specific video or country.
This report provides statistics for a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
User activity by country for specific time periods
This report provides statistics related to user actions on a channel for specific time intervals. You can filter the report to only return data for a specific video or country.
User activity in US states for specific time periods
This report provides statistics related to user activity for a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
This report provides statistics related to user activity on a country-by-country basis for a channel. You can filter the report to only return data for a specific video.
This report provides user activity statistics for US states and the District of Columbia. For this report, you must set the filters parameter value to country==US .
Note: This report requires you to set the maxResults parameter to an integer value of 250 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report provides user activity statistics by city.
This report provides user activity statistics by Designated Market Area (DMA). For this report, you must either set the filters parameter value to country==US or filter to a particular province (US state).
Playback detail reports provide statistics related to the following viewing attributes:
Was the view of a live video broadcast or an on-demand video?
Was the viewer subscribed to the channel that owns the video?
On which YouTube product did the view occur?
Note: The liveOrOnDemand dimension and filter cannot be used in conjunction with the averageViewPercentage metric. As such, each of the following subsections lists two reports. One report supports the liveOrOnDemand dimension (and filter), while the other supports the averageViewPercentage metric.
User activity by subscribed status
This report provides user activity metrics for subscribed and unsubscribed viewers. Statistics can be grouped by time period ( day or month ), and the report can also be filtered by country , continent , or subContinent .
This report provides user activity metrics for subscribed and unsubscribed viewers in US states or the District of Columbia. This report supports fewer metrics than the previous report.
The time dimension – day or month – is optional for these reports because, regardless, you need to use the startDate and endDate request parameters to specify the date range that the report will cover. The dimension, if present, indicates that you want data in the report to be aggregated by day, month, etc.
Playback details with optional time dimension and liveOrOnDemand statistics
This report provides playback detail statistics for specific time intervals. It supports the liveOrOnDemand dimension (and filter).
The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.
The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.
Note: This report requires you to set the maxResults parameter to an integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report identifies the embedded video players that generated the most views or viewing time for a channel's videos.
This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that stemmed from a Google search or from a link to a related video.
Note: This report requires you to set the maxResults parameter to an integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report aggregates viewing statistics based on the referrers that generated the most views for the channel's content. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available. For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the channel's content.
Note: This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.
Device type and operating system
Device type
This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that occurred on mobile devices or game consoles.
This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.
This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of views that occurred on Android tablets or on Windows desktop devices.
For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views andviewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)
You can use filters to ensure that the report only contains viewerPercentage data for one value (or combination of values) for playback detail dimensions.
Engagement and content sharing
This report provides statistics showing how frequently the channel's videos were shared on different social platforms.
This report measures a video's ability to retain its audience and also shows how often specific parts of a video were watched. The elapsedVideoTimeRatio dimension measures the amount of the video that has elapsed for the corresponding metric values. The metrics can be broken down into two categories:
Audience retention
These metrics show how well the video retains its audience.
audienceWatchRatio is a ratio that compares the number of times a portion of a video has been watched to the total number of views of the video.
relativeRetentionPerformance shows how well a video retains viewers during playbacks relative to other YouTube videos of a similar length.
Granular watch statistics
These metrics provide information about how often specific parts of a video were watched.
startedWatching indicates how often viewers started watching a video during a particular segment of the video.
stoppedWatching indicates how often viewers stopped watching a video during a particular segment of the video.
Note: This report does not support the ability to specify a comma-separated list of values for the video filter; the value must specify a single video ID.
This report shows the concurrent viewers at a given position for a single live-streamed video. The filter specifies the video. The position dimension generally represents a single minute.
Note: These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 videos. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.
Top videos with optional regional filters (<= 200 results)
This report lists the channel's top videos. The report can be filtered to list top videos by country , continent , or subContinent .
This report lists the channel's top videos in a particular US state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.
Top videos for subscribed or unsubscribed viewers (<= 200 results)
This report lists the channel's top videos for subscribed or unsubscribed viewers. The report can be filtered to list top videos by country , continent , or subContinent . The previous report lets you retrieve the top videos in a particular US state for subscribed or unsubscribed viewers, but it supports fewer metrics than this report.
This report lists the channel's top videos and supports playback detail and geographic filters. This report is similar to the previous one, but it supports fewer metrics and adds support for the youtubeProduct filter.
Playlist reports contain metrics related to user activity related to videos in the channel owner's playlists. Two versions of these reports are available, and, for each available report, the following sections contain a description of each version:
The Recommended tab in each section describes the preferred API request format for retrieving the corresponding report. The recommended reports support an expanded set of metrics that includes both aggregated video metrics and in-playlist metrics . This request format does not use the isCurated dimension.
The Using isCurated tab in each section describes an older API request format in which the isCurated dimension is required. These reports support in-playlist metrics only. Note that the isCurated dimension has been deprecated for all reports. The warning note below explains the deprecation schedule.
The following warning note explains changes between the two report versions in more detail.
Aggregated video metrics
These metrics provide user activity and impression metrics that are aggregated for all videos in the playlist that are also owned by the channel that owns the playlist. Metrics for videos owned by other channels are not computed in the aggregation. As a result, if a channel creates a playlist that contains only videos owned by other channels, reports for those playlists will not provide values for these metrics.
See the supported playlist metrics section for a list of aggregated video metrics that YouTube supports.
In-playlist metrics
These metrics reflect user activity and engagement in the context of the playlist page. These metrics include views for all videos in the playlist, regardless of which channel owns them, but only counts views that occurred in the playlist context.
This report provides statistics related to users' interactions with the videos in the channel's playlists. You can filter the report to only return data for a specific playlist.
This report provides statistics related to users' interactions with the videos in the channel's playlists. You can filter the report to only return data for a specific playlist.
This report provides playlist activity statistics for US states and the District of Columbia. For this report, you must filter results to return data only for the United States.
Note: This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report identifies the embedded video players that generated the most views or viewing time for the videos in the channel's playlists.
This report aggregates viewing statistics based on how viewers reached your playlist content. For example, it identifies the number of views that stemmed from a Google search.
Note: This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.
This report aggregates viewing statistics based on the referrers that generated the most views for the videos in the channel's playlists. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available.
For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the channel's playlists.
Note: This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.
Device type and operating system
Device type
This report aggregates viewing statistics based on how viewers reached the videos in your playlists. For example, it identifies the number of views that occurred on mobile devices or game consoles.
This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.
This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies how many views occurred on Android tablets or Windows desktop devices.
Note: The viewerPercentage values in this report are not normalized for different values of the subscribedStatus playback detail dimension.
For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views andviewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)
You can use filters to ensure that the report only contains viewerPercentage data for one value of the subscribedStatus dimensions.
Top playlists
Note: These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 playlists. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.
This report lists the channel's top playlists based on the specified filtering and sorting criteria.
Note: Ad performance reports require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.
Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions.
In addition, some video reports support the following playback-based ad performance metrics. However, these metrics are not included in ad performance reports.
[[["Прост для понимания","easyToUnderstand","thumb-up"],["Помог мне решить мою проблему","solvedMyProblem","thumb-up"],["Другое","otherUp","thumb-up"]],[["Отсутствует нужная мне информация","missingTheInformationINeed","thumb-down"],["Слишком сложен/слишком много шагов","tooComplicatedTooManySteps","thumb-down"],["Устарел","outOfDate","thumb-down"],["Проблема с переводом текста","translationIssue","thumb-down"],["Проблемы образцов/кода","samplesCodeIssue","thumb-down"],["Другое","otherDown","thumb-down"]],["Последнее обновление: 2025-01-03 UTC."],[],[]]
