Примечание.Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program .
На этой странице перечислены отчеты, которые владельцы контента могут получить с помощью API YouTube Analytics. Отчеты владельцев контента содержат показатели для каналов, связанных с указанным владельцем контента YouTube. Метрики – это отдельные показатели активности пользователей, эффективности рекламы или предполагаемого дохода.
Отчеты о видео содержат информацию о действиях пользователей, эффективности рекламы и предполагаемых показателях дохода от видео на каналах владельца контента.
Отчеты о списках воспроизведения предоставляют статистику, конкретно связанную с просмотрами видео, происходящими в контексте списка воспроизведения. В отчетах о плейлистах используются многие из тех же параметров и фильтров, что и в отчетах о видео.
Отчеты об эффективности рекламы содержат показатели, связанные с доходом и эффективностью рекламы. Они используют параметр adType для группировки показателей на основе типов рекламы, которая показывалась во время воспроизведения видео. В разделе отчетов об эффективности рекламы описаны два типа показателей эффективности рекламы, которые поддерживает API.
Получение отчета
Чтобы получить отчет владельца контента, вызовите метод API reports.query и установите значение параметра ids в запросе API на contentOwner== OWNER_NAME , где OWNER_NAME указывает идентификатор владельца контента. Если вы не уверены в ценности, обратитесь к своему менеджеру по работе с партнерами.
Авторизация
Все запросы API YouTube Analytics должны быть авторизованы. Руководство по авторизации объясняет, как использовать протокол OAuth 2.0 для получения токенов авторизации.
Запросы 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 .
Фильтры
Все запросы API для получения отчетов владельцев контента должны фильтровать данные, используя измерение video , измерение channel , измерение isCurated или поддерживаемую комбинацию измерений claimedStatus и uploaderType . (Поддерживаемые комбинации перечислены в определении измерения uploaderType .)
В таблицах, описывающих поддерживаемые отчеты, указаны фильтры, которые можно использовать для любого отчета. В описаниях фильтры, указанные в скобках, не являются обязательными. Например, если в отчете в качестве параметра фильтрации указано video(,country) , то отчет можно отфильтровать либо для включения данных только для определенного видео, либо для включения данных только для определенного видео в определенной стране.
API также поддерживает возможность указывать несколько значений для фильтров video , playlist и channel . Если вы укажете несколько значений для одного из этих фильтров, вы также можете добавить этот фильтр в список измерений, указанный для запроса. Это верно, даже если фильтр не указан в качестве поддерживаемого параметра для конкретного отчета.
См. определение параметра 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 или более: у вас есть возможность включить любое или все значения из группы.
Важно! Все запросы API на получение отчетов о видео владельца контента должны фильтровать данные, используя либо измерение видео , измерение канала , измерение группы или поддерживаемую комбинацию измерений заявленного статуса и типа загрузки . (Некоторые отчеты не поддерживают все эти параметры.) Поддерживаемые комбинации, которые также перечислены в определении измерения uploaderType :
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
Видеоотчеты
Основная статистика
Базовая статистика (включая количество подписчиков)
В этом отчете представлена статистика действий пользователей на всех каналах владельца контента. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео или страны. Его также можно использовать для получения статистики только по заявленному контенту, включая заявленный контент, загруженный владельцем контента, третьими лицами или ими обоими.
В этом отчете представлена статистика по конкретному штату США или округу Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
В этом отчете представлена статистика действий пользователей на всех каналах владельца контента за определенные промежутки времени. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео или страны.
Активность пользователей в штатах США за определенные периоды времени
В этом отчете представлена статистика по конкретному штату США или округу Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
В этом отчете представлена статистика активности пользователей по каждой стране для всех каналов владельца контента. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного видео или канала.
В этом отчете представлена статистика активности пользователей для штатов США и округа Колумбия. Для этого отчета необходимо установить значение параметра filterscountry==US .
Активность пользователей по городам (<= 250 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 250 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете представлена статистика активности пользователей по городам.
Подробные отчеты о воспроизведении содержат статистику, связанную со следующими атрибутами просмотра:
Был ли просмотр прямой видеотрансляции или видео по запросу?
Был ли зритель подписан на канал, которому принадлежит видео?
На каком продукте YouTube произошел просмотр?
Технически все параметры подробностей воспроизведения, поддерживаемые этими отчетами, не являются обязательными. Если вы не включите в свой запрос параметры подробностей воспроизведения, возвращаемый отчет фактически будет похож на один из базовых статистических отчетов , отчетов по времени или отчетов по географии пользователей .
Примечание. Измерение и фильтр liveOrOnDemand нельзя использовать вместе с метрикой AverageViewPercentage . Таким образом, в каждом из следующих подразделов перечислены два отчета. Один отчет поддерживает измерение (и фильтр) liveOrOnDemand , а другой — метрику AverageViewPercentage .
Активность пользователей по статусу подписки
В этом отчете представлены показатели активности пользователей для подписавшихся и отписавшихся зрителей. Статистика может быть сгруппирована по периоду времени ( день или месяц ), а также отчет можно отфильтровать по стране , континенту или субконтиненту .
Активность пользователей по статусу подписки для провинций
В этом отчете представлены показатели активности пользователей для подписавшихся и отписавшихся зрителей в штатах США или округе Колумбия. Этот отчет поддерживает меньше показателей, чем предыдущий отчет.
Детали воспроизведения с дополнительным измерением времени
Измерение времени — день или месяц — не является обязательным для этих отчетов, поскольку в любом случае вам необходимо использовать параметры запроса startDate и endDate , чтобы указать диапазон дат, который будет охватывать отчет. Измерение, если оно присутствует, указывает на то, что вы хотите, чтобы данные в отчете были агрегированы по дням, месяцам и т. д.
Детали воспроизведения с дополнительным измерением времени и статистикой liveOrOnDemand .
В этом отчете представлена подробная статистика воспроизведения за определенные интервалы времени. Он поддерживает измерение (и фильтр) liveOrOnDemand .
Следующий отчет аналогичен предыдущему. Он добавляет поддержку метрики AverageViewPercentage , но не поддерживает liveOrOnDemand в качестве измерения или фильтра.
Детали воспроизведения по провинциям со статистикой liveOrOnDemand
В этом отчете представлена подробная статистика воспроизведения для штатов США и округа Колумбия. Он поддерживает измерение (и фильтр) liveOrOnDemand .
Следующий отчет аналогичен предыдущему. Он добавляет поддержку метрики AverageViewPercentage , но не поддерживает liveOrOnDemand в качестве измерения или фильтра.
Подробности о месте воспроизведения (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете указаны встроенные видеоплееры, которые обеспечили наибольшее количество просмотров или времени просмотра контента владельца контента. При получении этого отчета необходимо установить для фильтра insightPlaybackLocationType значение EMBEDDED .
В этом отчете собрана статистика просмотров на основе того, каким образом зрители добрались до вашего видеоконтента. Например, он определяет количество просмотров, полученных в результате поиска в Google или по ссылке на похожее видео.
Примечание. Этот отчет возвращает ошибку, если произведение количества запрошенных видео на число дней в диапазоне дат превышает 50 000. Например, запрос, который получает данные для 500 идентификаторов видео, может запрашивать данные максимум за 100 дней. Чтобы уменьшить количество строк, возвращаемых запросом, разделите запрос на несколько запросов, которые указывают меньшее количество видео или устанавливают более короткие диапазоны дат.
Подробности об источнике трафика (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете собрана статистика просмотров на основе источников перехода, которые сгенерировали наибольшее количество просмотров контента владельца контента. Рефереры классифицируются по типу источника трафика, а определение измерения InsightTrafficSourceDetail определяет источники трафика, для которых доступен отчет. Например, если вы установите для фильтра InsightTrafficSourceType значение ADVERTISING , в отчете будут перечислены типы объявлений, которые вызвали наибольшее количество просмотров или время просмотра контента владельца контента.
Примечание. Этот отчет поддерживается только для определенных источников трафика. Источники трафика VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED относятся к числу неподдерживаемых.
Тип устройства и операционная система
Тип устройства
В этом отчете собрана статистика просмотров в зависимости от типа устройства, которое зрители использовали при просмотре вашего контента. Например, он определяет количество просмотров, произошедших на планшетах или игровых консолях.
В этом отчете собрана статистика просмотров на основе операционных систем зрителей. Например, он определяет количество просмотров, произошедших на устройствах Android или на PlayStation.
В этом отчете собрана статистика просмотров на основе операционных систем и типов устройств зрителей. Например, он определяет количество просмотров, произошедших на планшетах Android или на настольных устройствах Windows.
Примечание. Значения ViewerPercentage в этом отчете не нормализованы для различных значений параметра подробностей воспроизведения subscribedStatus .
Например, если в отчете используется измерение subscribedStatus , то он возвращает данныеviewerPercentage, добавляющие до 100 процентов для просмотров, на которые есть подписка , иданныеviewerPercentage , добавляющие до 100 процентов, для просмотров, на которые не подписаны. (Общее значение всех полей viewerpercentage в отчете составляет 200 процентов.)
В этом отчете измеряется способность видео удерживать аудиторию. Измерение elapsedVideoTimeRatio измеряет количество прошедшего видео для соответствующих значений показателя. Метрики audienceWatchRatio и relativeRetentionPerformance предоставляют два показателя, которые показывают, насколько хорошо видео удерживает свою аудиторию. Первое значение является абсолютным, а второе показывает, как видео работает по сравнению с другими видео YouTube аналогичной длины.
Примечание. Отчеты об удержании аудитории не поддерживают возможность указать список значений, разделенных запятыми, для video ; значение должно указывать один идентификатор видео.
Примечание. Для этих отчетов необходимо установить для параметра maxResults целое значение 200 или меньше. До 1 января 2013 г. данные доступны только для 10 лучших видео. В отличие от большинства других отчетов, эти отчеты также требуют указания значения параметра запроса sort .
Лучшие видео в целом по стране, континенту или субконтиненту (<= 200 результатов)
В этом отчете перечислены самые популярные видео владельца контента на основе указанных критериев фильтрации и сортировки.
В этом отчете перечислены самые популярные видео владельца контента в конкретном штате США или округе Колумбия. Обратите внимание, что этот отчет поддерживает только часть показателей, доступных в отчете по конкретной стране, описанном выше.
Лучшие видео для подписавшихся или отписавшихся зрителей (<= 200 результатов)
В этом отчете перечислены самые популярные видео для подписавшихся или отписавшихся зрителей. Отчет можно отфильтровать, чтобы получить список лучших видео по стране , континенту или субконтиненту . Предыдущий отчет позволяет получить самые популярные видео в определенном штате США для подписавшихся или отписавшихся зрителей, но он поддерживает меньше показателей, чем этот отчет.
Лучшие видео по продуктам YouTube (<= 200 результатов)
В этом отчете перечислены самые популярные видео, а также поддерживаются подробные сведения о воспроизведении и географические фильтры. Этот отчет похож на предыдущий, но поддерживает меньше показателей и добавляет поддержку фильтра youtubeProduct .
Лучшие видео с фильтрами подробностей воспроизведения (<= 200 результатов)
В этом отчете перечислены самые популярные видео владельца контента, отфильтрованные по одному или нескольким параметрам детализации воспроизведения: liveOrOnDemand , subscribedStatus и youtubeProduct . Отчет также поддерживает фильтрацию по региону.
Отчеты о плейлистах содержат показатели, связанные с активностью пользователей, связанной с видео в плейлистах владельца канала. Доступны две версии этих отчетов, и для каждого доступного отчета следующие разделы содержат описание каждой версии:
На вкладке «Рекомендовано» в каждом разделе описан предпочтительный формат запроса API для получения соответствующего отчета. Рекомендуемые отчеты поддерживают расширенный набор показателей, включающий как совокупные показатели видео , так и показатели плейлиста . Этот формат запроса не использует измерение isCurated .
На вкладке «Использование isCurated в каждом разделе описан более старый формат запроса API, в котором требуется измерение isCurated . Эти отчеты поддерживают только показатели плейлиста . Обратите внимание, что параметр isCurated устарел для всех отчетов. В примечании ниже поясняется график прекращения поддержки.
В следующем примечании к предупреждению более подробно объясняются различия между двумя версиями отчета.
Совокупные показатели видео
Эти метрики предоставляют показатели активности пользователей и показов, которые суммируются для всех видео в плейлисте, которые также принадлежат каналу, которому принадлежит плейлист. Показатели видео, принадлежащих другим каналам, при агрегировании не рассчитываются. В результате, если канал создает плейлист, содержащий только видео, принадлежащие другим каналам, в отчетах по этим плейлистам не будут указаны значения этих показателей.
Эти показатели отражают активность и вовлеченность пользователей в контексте страницы плейлиста. Эти показатели включают просмотры всех видео в плейлисте, независимо от того, какому каналу они принадлежат, но учитываются только просмотры, произошедшие в контексте плейлиста.
В этом отчете представлена статистика взаимодействия пользователей с видео в плейлистах на каналах владельца контента. В отчете нет обязательных измерений.
В этом отчете представлена статистика взаимодействия пользователей с видео в плейлистах на каналах владельца контента за определенные промежутки времени. Вы можете отфильтровать отчет, чтобы возвращать данные только для определенного плейлиста или канала.
В этом отчете представлена статистика активности плейлистов для штатов США и округа Колумбия. Для этого отчета вы включаете country==US в значение параметра filters .
Подробности о месте воспроизведения (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете указаны встроенные видеопроигрыватели, которые обеспечили наибольшее количество просмотров или времени просмотра плейлистов владельца контента.
В этом отчете собрана статистика просмотров на основе того, каким образом зрители добрались до содержимого вашего плейлиста. Например, он определяет количество просмотров, полученных в результате поиска Google или страницы канала.
Подробности об источнике трафика (<= 25 результатов)
Примечание. Для этого отчета необходимо установить для параметра maxResults целое значение 25 или меньше. В отличие от большинства других отчетов, в этом отчете также требуется указать значение параметра запроса sort .
В этом отчете собрана статистика просмотров на основе источников перехода, которые сгенерировали наибольшее количество просмотров плейлистов владельца контента. Рефереры классифицируются по типу источника трафика, а определение измерения InsightTrafficSourceDetail определяет источники трафика, для которых доступен отчет. Например, если вы установите для фильтра InsightTrafficSourceType значение ADVERTISING , в отчете будут перечислены типы рекламы, которые вызвали наибольшее количество просмотров или время просмотра для плейлистов владельца контента.
Примечание. Этот отчет поддерживается только для определенных источников трафика. Источники трафика VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES и NO_LINK_EMBEDDED относятся к числу неподдерживаемых.
Тип устройства и операционная система
Тип устройства для плейлистов
В этом отчете собрана статистика просмотров в зависимости от типа устройства, которое зрители использовали для просмотра содержимого вашего плейлиста. Например, он определяет количество просмотров, произошедших на мобильных устройствах или игровых консолях.
В этом отчете собрана статистика просмотров на основе операционных систем зрителей. Например, он определяет количество просмотров плейлистов на устройствах Android или PlayStation.
Операционная система и тип устройства для плейлистов
В этом отчете собрана статистика просмотров на основе операционных систем и типов устройств зрителей. Например, он определяет количество просмотров плейлистов, произошедших на планшетах Android или на настольных устройствах Windows.
Примечание. Значения viewerPercentage в этом отчете не нормализованы для различных значений или комбинаций значений параметров подробностей воспроизведения ( subscribedStatus и youtubeProduct ).
Например, отчет, в котором используется измерение subscribedStatus , возвращает данныеviewerPercentage, добавляющие до 100 процентов для просмотров, на которые есть подписка , иданныеviewerPercentage, добавляющие до 100 процентов, для просмотров, на которые не подписаны. (Общее значение всех полей viewerpercentage в отчете составляет 200 процентов.)
Вы можете использовать фильтры, чтобы гарантировать, что отчет содержит только данные ViewerPercentage для одного значения (или комбинации значений) для параметров подробностей воспроизведения.
Лучшие плейлисты
Примечание. Для этих отчетов необходимо установить для параметра maxResults целое значение 200 или меньше. До 1 января 2013 г. данные доступны только для 10 лучших плейлистов. В отличие от большинства других отчетов, эти отчеты также требуют указания значения параметра запроса sort .
В этом отчете перечислены лучшие плейлисты владельца контента на основе указанных критериев фильтрации и сортировки.
Примечание. Для отчетов об эффективности рекламы требуется токен авторизации, который предоставляет доступ к области https://www.googleapis.com/auth/yt-analytics-monetary.readonly .
В отчетах об эффективности рекламы представлены показатели показов объявлений, которые показывались во время воспроизведения видео. Эти показатели учитывают каждый показ рекламы, и каждое воспроизведение видео может привести к нескольким показам.
Показатели эффективности рекламы на основе показов:
Кроме того, некоторые отчеты по видео поддерживают следующие показатели эффективности рекламы на основе воспроизведения. Однако эти показатели не включаются в отчеты об эффективности рекламы.
