Observação:Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.
Esta página lista os relatórios que os proprietários de conteúdo podem recuperar com a API YouTube Analytics. Os relatórios do proprietário do conteúdo incluem métricas de canais vinculados a um proprietário do conteúdo do YouTube específico. As métricas são medições individuais da atividade do usuário, do desempenho do anúncio ou da receita estimada.
Os relatórios de vídeo contêm métricas de atividade do usuário, desempenho do anúncio e receita estimada dos vídeos nos canais de um proprietário de conteúdo.
Os relatórios de playlists mostram estatísticas relacionadas especificamente às visualizações de vídeo que ocorrem no contexto de uma playlist. Os relatórios de playlist usam muitas das mesmas dimensões e filtros dos relatórios de vídeo.
Os relatórios de performance de anúncios contêm métricas relacionadas à receita e ao desempenho do anúncio. Eles usam a dimensão adType para agrupar métricas com base nos tipos de anúncios veiculados durante a reprodução de vídeo. A seção Relatórios de performance do anúncio explica os dois tipos de métricas de performance do anúncio com suporte da API.
Como recuperar um relatório
Para recuperar um relatório do proprietário de conteúdo, chame o método reports.query da API e defina o valor do parâmetro ids na solicitação da API como contentOwner==OWNER_NAME, em que OWNER_NAME especifica o ID do proprietário do conteúdo. Pergunte ao gerente de parcerias se você não tiver certeza do valor.
Autorização
Todas as solicitações da API YouTube Analytics precisam ser autorizadas. O guia de autorização explica como usar o protocolo OAuth 2.0 para recuperar tokens de autorização.
As solicitações da API YouTube Analytics usam os seguintes escopos de autorização:
Visualizar os relatórios do YouTube Analytics para seu conteúdo do YouTube. Este escopo fornece acesso às métricas de atividade do usuário, como contagens de visualização e de classificação.
Visualizar os relatórios monetários do YouTube Analytics para seu conteúdo do YouTube. Esse escopo dá acesso às métricas de atividade do usuário e às métricas de receita estimada e performance do anúncio.
https://www.googleapis.com/auth/youtube
Gerenciar sua conta do YouTube. Na API YouTube Analytics, os proprietários de canais usam esse escopo para gerenciar grupos e itens de grupo do YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner
Acessar e gerenciar recursos e conteúdo associado no YouTube. Na API YouTube Analytics, os proprietários de conteúdo usam esse escopo para gerenciar grupos e itens de grupo do YouTube Analytics.
Observação:as métricas marcadas com um asterisco (*) exigem um token de autorização que conceda acesso ao escopo https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Filtros
Todas as solicitações de API para recuperar relatórios do proprietário de conteúdo precisam filtrar dados usando a dimensão video, channel ou isCurated ou uma combinação compatível das dimensões claimedStatus e uploaderType. As combinações compatíveis estão listadas na definição da dimensão uploaderType.
As tabelas que explicam os relatórios compatíveis identificam os filtros que podem ser usados em cada um deles. Nas descrições, os filtros mostrados entre parênteses são opcionais. Por exemplo, se um relatório listar video(,country) como uma opção de filtragem, ele poderá ser filtrado para incluir apenas dados de um vídeo específico ou apenas dados de um vídeo específico em um país específico.
A API também oferece suporte à capacidade de especificar vários valores para os filtros video, playlist e channel. Se você especificar vários valores para um desses filtros, também poderá adicionar esse filtro à lista de dimensões especificada para a solicitação. Isso é válido mesmo que o filtro não esteja listado como uma dimensão compatível com um relatório específico.
Consulte a definição do parâmetro filters para uma explicação completa sobre como filtrar os resultados da API para um valor ou conjunto de valores específico.
Sobre as tabelas de relatórios
Esta seção explica a formatação e a terminologia usadas nas tabelas que definem os relatórios compatíveis com a API. A tabela a seguir lista as dimensões, métricas e filtros compatíveis com o
Relatório de detalhes de reprodução de vídeo usando a dimensão de tempo e a métrica averageViewPercentage.
A tabela contém duas linhas para dimensões, uma para métricas e três para filtros. Para dimensões e filtros, os valores de cada linha podem ser combinados em uma solicitação de API, desde que a combinação siga as regras de uso na tabela. Por exemplo, os valores de parâmetro dimensions válidos para esse relatório incluem:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
No entanto, o valor do parâmetro day,month é inválido porque usa duas dimensões baseadas em tempo, e a solicitação precisa usar 0 ou 1.
Terminologia da tabela de relatórios
As tabelas usam a seguinte terminologia para indicar se as dimensões são obrigatórias ou opcionais:
Estes termos significam que um valor é obrigatório:
Obrigatório:é necessário incluir o valor.
Usar exatamente 1:é necessário incluir um valor do grupo.
Usar um ou mais:é possível incluir qualquer valor do grupo, mas é necessário incluir pelo menos um.
Estes termos significam que um valor é opcional:
Opcional:você tem a opção de incluir o valor.
Usar 0 ou 1:você tem a opção de incluir um valor do grupo.
Usar 0 ou mais:você tem a opção de incluir qualquer valor ou todos os valores do grupo.
Importante:todas as solicitações de API para recuperar relatórios de vídeo do proprietário de conteúdo precisam
filtrar dados usando a dimensão video, a dimensão channel, a dimensão group
ou uma combinação compatível das dimensões claimedStatus e uploaderType. Alguns relatórios não são compatíveis com todas essas opções. As combinações compatíveis, que
também estão listadas na definição da dimensão uploaderType, são:
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
Relatórios de vídeo
Estatísticas básicas
Estatísticas básicas (incluindo contagem de inscritos)
Esse relatório mostra estatísticas relacionadas às ações dos usuários em todos os canais de um proprietário de conteúdo. É possível filtrar o relatório para retornar somente os dados de um vídeo ou país específicos. Ele também pode ser usado para recuperar apenas as estatísticas de conteúdo reivindicado, incluindo conteúdo reivindicado enviado pelo proprietário do conteúdo, por terceiros ou por ambos.
Neste relatório, são exibidas as estatísticas para um estado específico nos EUA ou para o Distrito de Columbia. Ele é compatível apenas com um subconjunto das métricas disponíveis no relatório de país específico descrito acima.
Esse relatório mostra estatísticas relacionadas às ações dos usuários em todos os canais de um proprietário de conteúdo em intervalos de tempo específicos. É possível filtrar o relatório para retornar somente os dados de um vídeo ou país específicos.
Atividade do usuário em estados nos EUA em períodos específicos
Neste relatório, são exibidas as estatísticas para um estado específico nos EUA ou para o Distrito de Columbia. Ele é compatível apenas com um subconjunto das métricas disponíveis no relatório de país específico descrito acima.
Esse relatório mostra estatísticas relacionadas à atividade do usuário por país para todos os canais de um proprietário de conteúdo. É possível filtrar o relatório para que ele retorne apenas dados de um vídeo ou canal específico.
Neste relatório, são exibidas as estatísticas da atividade do usuário para estados nos EUA e para o Distrito de Columbia. Para esse relatório, defina o valor do parâmetro filters como country==US.
Atividade do usuário por cidade (até 250 resultados)
Observação:para gerar esse relatório, é necessário definir o parâmetro maxResults como um valor inteiro de 250 ou menos. Ao contrário da maioria dos outros relatórios, esse relatório também exige que você especifique um valor para o parâmetro de solicitação sort.
Este relatório mostra as estatísticas de atividade do usuário por cidade.
Os relatórios de detalhes da reprodução fornecem estatísticas relacionadas aos seguintes atributos de visualização:
A visualização foi de uma transmissão ao vivo ou de um vídeo sob demanda?
O espectador estava inscrito no canal do proprietário do vídeo?
Em qual produto do YouTube a visualização ocorreu?
Tecnicamente, as dimensões de detalhes de reprodução compatíveis com esses relatórios são opcionais. Se você não incluir dimensões de detalhes de reprodução na solicitação, o relatório retornado será semelhante a um dos relatórios de estatísticas básicas, baseado em tempo ou geografia do usuário.
Observação:a dimensão e o filtro liveOrOnDemand não podem ser usados com a métrica averageViewPercentage. Portanto, cada uma das subseções a seguir lista dois relatórios. Um relatório aceita a dimensão (e o filtro) liveOrOnDemand, e o outro aceita a métrica averageViewPercentage.
Atividade do usuário por status de inscrição
Esse relatório mostra as métricas de atividade do usuário para espectadores inscritos e não inscritos. As estatísticas podem ser agrupadas por período (dia ou mês), e o relatório também pode ser filtrado por país, continente ou subContinent.
Atividade do usuário por status de inscrição em províncias
Esse relatório mostra as métricas de atividade do usuário para espectadores inscritos e não inscritos nos estados dos EUA ou no Distrito de Columbia. Esse relatório tem menos métricas do que o anterior.
Detalhes da reprodução com dimensão de tempo opcional
A dimensão de tempo (dia ou mês) é opcional para esses relatórios porque, de qualquer forma, você precisa usar os parâmetros de solicitação startDate e endDate para especificar o período que o relatório vai abranger. Se presente, a dimensão indica que você quer que os dados no relatório sejam agregados por dia, mês etc.
Detalhes da reprodução com a dimensão de tempo opcional e estatísticas liveOrOnDemand
Esse relatório mostra estatísticas detalhadas sobre a reprodução em intervalos de tempo específicos. Ele aceita a dimensão (e o filtro) liveOrOnDemand.
O relatório a seguir é semelhante ao anterior. Ele adiciona suporte à métrica averageViewPercentage, mas não oferece suporte a liveOrOnDemand como uma dimensão ou um filtro.
Detalhes da reprodução por província com estatísticas liveOrOnDemand
Este relatório mostra estatísticas detalhadas de reprodução para os estados dos EUA e o Distrito de Columbia. Ele aceita a dimensão (e o filtro) liveOrOnDemand.
O relatório a seguir é semelhante ao anterior. Ele adiciona suporte à métrica averageViewPercentage, mas não oferece suporte a liveOrOnDemand como uma dimensão ou um filtro.
Detalhes do local da visualização (até 25 resultados)
Observação:para gerar esse relatório, é necessário definir o parâmetro maxResults como um valor inteiro de 25 ou menos. Ao contrário da maioria dos outros relatórios, esse relatório também exige que você especifique um valor para o parâmetro de solicitação sort.
Esse relatório identifica os players de vídeo incorporados que geraram mais visualizações ou tempo de exibição para o conteúdo de um proprietário. Ao extrair esse relatório, defina o filtro insightPlaybackLocationType como EMBEDDED.
Esse relatório agrega estatísticas de visualização com base na forma como os espectadores acessaram seu conteúdo
em vídeo. Por exemplo, ele identifica o número de visualizações que vieram de uma pesquisa no Google ou de
um link para um vídeo relacionado.
Observação:esse relatório vai retornar um erro se o produto de
# de vídeos consultados X # de dias no período exceder 50.000. Por exemplo, uma consulta
que recupera dados de 500 IDs de vídeo pode solicitar dados por um máximo de 100 dias. Para reduzir o
número de linhas que uma solicitação retorna, divida a consulta em várias consultas que especifiquem menos
vídeos ou defina períodos mais curtos.
Observação:para gerar esse relatório, é necessário definir o parâmetro maxResults como um valor inteiro de 25 ou menos. Ao contrário da maioria dos outros relatórios, esse relatório também exige que você especifique um valor para o parâmetro de solicitação sort.
Esse relatório agrega estatísticas de visualização com base nos sites de origem que geraram mais visualizações para o conteúdo do proprietário. Os referenciadores são categorizados por tipo de origem do tráfego, e na definição da dimensão insightTrafficSourceDetail são identificadas as origens do tráfego para o qual o relatório está disponível. Por exemplo, se você definir o filtro insightTrafficSourceType como ADVERTISING, o relatório vai listar os tipos de anúncios que geraram mais visualizações ou tempo de exibição para o conteúdo do proprietário.
Nota: este relatório é compatível apenas com origens do tráfego específicas. As origens de tráfego VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES e NO_LINK_EMBEDDED são algumas das que não são compatíveis.
Tipo de dispositivo e sistema operacional
Tipo de dispositivo
Esse relatório agrega estatísticas de visualização com base no tipo de dispositivo que os espectadores usaram para assistir seu conteúdo. Por exemplo, ele identifica o número de visualizações que ocorreram em tablets ou consoles de jogos.
Neste relatório, são agregadas as estatísticas de visualização com base nos sistemas operacionais dos espectadores. Por exemplo, nele é identificado o número de visualizações que ocorreram em dispositivos Android ou em PlayStations.
Neste relatório, são agregadas as estatísticas de visualização com base nos sistemas operacionais e nos tipos de dispositivo dos espectadores. Por exemplo, nele é identificado o número de visualizações que ocorreram em tablets Android ou em computadores com Windows.
Observação:os valores de viewerPercentage neste relatório não são normalizados
para valores diferentes da dimensão de detalhes de reprodução subscribedStatus.
Por exemplo,
se um relatório usa a dimensão subscribedStatus, ele retorna dados de viewerPercentage
somando até 100% para visualizações de inscritos e dados de viewerPercentage somando
até 100% para visualizações de não inscritos. O valor total de todos os campos viewerPercentage no relatório é 200%.
Você pode usar filtros para garantir que o relatório contenha apenas dados de viewerPercentage para um valor da dimensão subscribedStatus.
Engajamento e compartilhamento de conteúdo
Neste relatório, são exibidas as estatísticas da frequência em que vídeos do canal foram compartilhados em diferentes plataformas sociais.
Esse relatório mede a capacidade de um vídeo em manter o público assistindo. A dimensão elapsedVideoTimeRatio mede a quantidade de vídeo que decorreu para os valores de métrica correspondentes. As métricas audienceWatchRatio e relativeRetentionPerformance fornecem duas medidas que mostram a eficiência do vídeo em manter o público assistindo. O primeiro é um valor absoluto, e o segundo mostra a performance do vídeo em relação a outros vídeos do YouTube com duração semelhante.
Observação:os relatórios de retenção de público-alvo não permitem especificar uma lista de valores separados por vírgulas para o filtro video. O valor precisa especificar um único ID de vídeo.
Observação:esses relatórios exigem que você defina o parâmetro maxResults como um valor inteiro de 200 ou menos. Os dados anteriores a 1º de janeiro de 2013 estão disponíveis apenas para os 10 vídeos mais assistidos. Ao contrário da maioria dos outros relatórios, esses relatórios também exigem que você especifique um valor para o parâmetro de solicitação sort.
Os principais vídeos no geral, por país, continente ou subcontinente (até 200 resultados)
Este relatório lista os principais vídeos do proprietário do conteúdo com base nos critérios de filtragem e classificação especificados.
Principais vídeos por estado dos EUA (até 200 resultados)
Este relatório lista os principais vídeos do proprietário de conteúdo em um estado dos EUA ou no Distrito de Columbia. Ele é compatível apenas com um subconjunto das métricas disponíveis no relatório de país específico descrito acima.
Principais vídeos para espectadores inscritos ou não inscritos(<= 200 resultados)
Esse relatório lista os principais vídeos para espectadores inscritos ou não inscritos. O relatório pode ser filtrado para listar os principais vídeos por país, continente ou subContinent. O relatório anterior permite que você extraia os vídeos mais assistidos em um determinado estado dos EUA para espectadores inscritos ou não inscritos, mas ele tem menos métricas do que este relatório.
Vídeos mais acessados por produto do YouTube (até 200 resultados)
Esse relatório lista os principais vídeos e oferece suporte a detalhes de reprodução e filtros geográficos. Esse relatório é semelhante ao anterior, mas oferece suporte a menos métricas e adiciona suporte ao filtro youtubeProduct.
Principais vídeos com filtros de detalhes de reprodução (até 200 resultados)
Este relatório lista os principais vídeos do proprietário do conteúdo, filtrando por uma ou mais dimensões de detalhes de reprodução: liveOrOnDemand, subscribedStatus e youtubeProduct. O relatório também oferece suporte à filtragem por região.
Os relatórios de playlist contêm métricas relacionadas à atividade do usuário em vídeos nas playlists do proprietário do canal. Há duas versões desses relatórios disponíveis, e, para cada um deles,
as seções a seguir contêm uma descrição de cada versão:
A guia Recomendada em cada seção descreve o formato de solicitação de API preferencial para
extrair o relatório correspondente. Os relatórios recomendados oferecem suporte a um conjunto mais amplo de métricas,
que inclui métricas de vídeo agregadas e
métricas na playlist. Esse formato de solicitação não usa a dimensão isCurated.
A guia Usar isCurated em cada seção descreve um formato de solicitação de API mais antigo em que a dimensão isCurated é necessária. Esses relatórios são compatíveis apenas com as métricas da playlist. A dimensão isCurated foi descontinuada para todos os relatórios. A observação de aviso abaixo
explica o cronograma de descontinuação.
A nota de aviso a seguir explica as mudanças entre as duas versões do relatório com mais detalhes.
Métricas de vídeo agregadas
Essas métricas fornecem informações sobre impressões e atividade do usuário que são agregadas para todos os vídeos
da playlist que também pertencem ao canal que a possui. As métricas de vídeos
de outros canais não são computadas na agregação. Como resultado, se um canal criar uma
playlist que contém apenas vídeos de outros canais, os relatórios dessas playlists não
vão mostrar valores para essas métricas.
Essas métricas refletem a atividade e o engajamento do usuário no contexto da página da playlist. Essas
métricas incluem visualizações de todos os vídeos da playlist, independentemente de qual canal é o proprietário, mas
só contam as visualizações que ocorreram no contexto da playlist.
Esse relatório mostra estatísticas relacionadas às interações dos usuários com os vídeos nas playlists
dos canais de um proprietário de conteúdo. O relatório não tem as dimensões necessárias.
Esse relatório mostra estatísticas relacionadas às interações dos usuários com os vídeos em playlists dos
canais de um proprietário de conteúdo em intervalos de tempo específicos. É possível filtrar o relatório para retornar apenas
dados de uma playlist ou canal específico.
Este relatório mostra as estatísticas de atividade das playlists nos estados dos EUA e no Distrito de Columbia. Para este relatório, inclua country==US no valor do parâmetro filters.
Detalhes do local da visualização (até 25 resultados)
Observação:para gerar esse relatório, é necessário definir o parâmetro maxResults como um valor inteiro de 25 ou menos. Ao contrário da maioria dos outros relatórios, esse relatório também exige que você especifique um valor para o parâmetro de solicitação sort.
Esse relatório identifica os players de vídeo incorporados que geraram mais visualizações ou tempo de exibição para as playlists de um proprietário de conteúdo.
Esse relatório agrega estatísticas de visualização com base na forma como os espectadores acessaram o conteúdo da playlist. Por exemplo, ele identifica o número de visualizações que vieram de uma pesquisa no Google ou de uma página de canal.
Observação:para gerar esse relatório, é necessário definir o parâmetro maxResults como um valor inteiro de 25 ou menos. Ao contrário da maioria dos outros relatórios, esse relatório também exige que você especifique um valor para o parâmetro de solicitação sort.
Esse relatório agrega estatísticas de visualização com base nos sites de origem que geraram mais visualizações para as playlists do proprietário do conteúdo. Os referenciadores são categorizados por tipo de origem do tráfego, e na definição da dimensão insightTrafficSourceDetail são identificadas as origens do tráfego para o qual o relatório está disponível. Por exemplo, se você definir o filtro insightTrafficSourceType como ADVERTISING, o relatório vai listar os tipos de anúncios que geraram mais visualizações ou tempo de exibição para as playlists do proprietário do conteúdo.
Nota: este relatório é compatível apenas com origens do tráfego específicas. As origens de tráfego VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES e NO_LINK_EMBEDDED são algumas das que não são compatíveis.
Tipo de dispositivo e sistema operacional
Tipo de dispositivo para playlists
Esse relatório agrega estatísticas de visualização com base no tipo de dispositivo usado pelos espectadores para assistir o conteúdo da playlist. Por exemplo, ele identifica o número de visualizações que ocorreram em dispositivos móveis ou consoles de jogos.
Neste relatório, são agregadas as estatísticas de visualização com base nos sistemas operacionais dos espectadores. Por exemplo, ele identifica o número de visualizações de playlist que ocorreram em dispositivos Android ou PlayStations.
Sistema operacional e tipo de dispositivo para playlists
Neste relatório, são agregadas as estatísticas de visualização com base nos sistemas operacionais e nos tipos de dispositivo dos espectadores. Por exemplo, ele identifica o número de visualizações de playlist que ocorreram em tablets Android ou em dispositivos desktop Windows.
Observação:os valores de viewerPercentage neste relatório não são normalizados para diferentes valores ou combinações de valores para dimensões de detalhes de reprodução (subscribedStatus e youtubeProduct).
Por exemplo, um relatório que usa a dimensão subscribedStatus retorna dados de viewerPercentage que somam 100% para visualizações de inscritos e dados de viewerPercentage que somam 100% para visualizações de não inscritos. O valor total de todos os campos viewerPercentage no relatório é 200%.
É possível usar filtros para garantir que o relatório contenha apenas dados de viewerPercentage para um valor (ou combinação de valores) nas dimensões de detalhes de reprodução.
Playlists mais acessadas
Observação:esses relatórios exigem que você defina o parâmetro maxResults como um valor inteiro de 200 ou menos. Os dados anteriores a 1º de janeiro de 2013 estão disponíveis apenas para as 10 principais playlists. Ao contrário da maioria dos outros relatórios, esses relatórios também exigem que você especifique um valor para o parâmetro de solicitação sort.
Este relatório lista as principais playlists do proprietário do conteúdo com base nos critérios de filtragem e classificação especificados.
Observação:os relatórios de performance de anúncios exigem um token de autorização que conceda acesso ao escopo https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Os relatórios de performance dos anúncios fornecem métricas baseadas em impressões para anúncios veiculados durante a reprodução de vídeos. Essas métricas representam cada impressão de anúncio, e cada reprodução de vídeo pode gerar várias impressões.
As métricas de performance de anúncios com base em impressões são:
Além disso, alguns relatórios de vídeo oferecem suporte às seguintes métricas de performance de anúncios com base na reprodução: No entanto, essas métricas não são incluídas nos relatórios de performance do anúncio.
