Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta página lista relatórios que os proprietários de canais podem recuperar com a API YouTube Analytics. Os relatórios de canais fornecem métricas da atividade do usuário de um canal específico e medem coisas como exibições de vídeos, classificações e contagens de inscrições.
Os relatórios de vídeo fornecem estatísticas de toda a atividade do usuário relacionada aos vídeos de um canal.
Os relatórios de playlist apresentam estatísticas especificamente relacionadas às exibições de vídeos que ocorrem no contexto de uma playlist.
Os relatórios de performance de anúncios contêm métricas relacionadas à receita e ao desempenho dos anúncios. Eles usam a dimensão adType para agrupar métricas com base nos tipos de anúncios que são exibidos durante as reproduções de vídeo. A seção Relatórios de desempenho de anúncios explica os dois tipos de métricas de desempenho de anúncios que a API suporta.
Como recuperar um relatório
Para recuperar um relatório de canal, é necessário definir o valor do parâmetro ids na sua solicitação de API como um destes valores:
channel==MINE: a API retorna dados do canal do YouTube do usuário autenticado.
channel==CHANNEL_ID: defina CHANNEL_ID como o ID exclusivo do canal para o qual você está recuperando dados. O usuário que autoriza a solicitação precisa ser o proprietário do canal.
Atualmente, o ID do canal é uma string que começa com as letras UC, embora o formato esteja sujeito a mudanças. Você pode encontrar o ID do canal na página Configurações avançadas da conta do seu canal do YouTube ou recuperar o ID programaticamente usando o método YouTube Data API'schannels.list.
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 fornece acesso às métricas de atividade do usuário, à receita estimada e ao desempenho de anúncios.
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 grupos do YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner
Veja e gerencie os recursos e conteúdos associados do YouTube na plataforma. Na API YouTube Analytics, os proprietários de conteúdo usam esse escopo para gerenciar grupos e itens de grupos do YouTube Analytics.
Observação:no momento, a receita estimada e as métricas de desempenho de anúncios não são compatíveis com relatórios de canais. Por isso, o escopo https://www.googleapis.com/auth/yt-analytics-monetary.readonly não concede acesso a dados monetários nesses relatórios.
Filtros
As tabelas que explicam os relatórios compatíveis identificam os filtros que podem ser usados para cada relatório. Nas tabelas, os filtros entre parênteses são opcionais. Por exemplo, para a opção de filtragem video(,country), o filtro video é obrigatório, e o filtro country é opcional.
A API também permite especificar vários valores para os filtros video e playlist. Se você especificar diversos valores para um desses filtros, também poderá adicionar esse filtro à lista de dimensões especificadas para a solicitação. Isso acontece mesmo que o filtro não esteja listado como uma dimensão compatível com um determinado relatório.
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.
Como interpretar 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 abaixo 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 linhas 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 válidos do parâmetro dimensions para esse relatório incluem:
dimensions=day
dimensions=day,liveOrOnDemand
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
No entanto, o valor do parâmetro day,month é inválido porque usa duas dimensões com base no tempo, mas a solicitação pode usar 0 ou 1. Nesse caso, o valor de parâmetro subscribedStatus,youtubeProduct retorna um relatório, mas as métricas não são agregadas por dia, semana, mês etc. Esse relatório é documentado separadamente na documentação.
Terminologia da tabela de relatórios
As tabelas usam a terminologia a seguir para indicar se as dimensões são obrigatórias ou opcionais:
Esses termos significam que um valor é necessário:
Obrigatório:você precisa incluir o valor.
Usar exatamente 1:você precisa incluir um valor do grupo.
Usar 1 ou mais:você pode incluir qualquer um ou todos os valores do grupo, mas precisa incluir pelo menos um.
Esses 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 um ou todos os valores do grupo.
Relatórios de vídeo
Estatísticas básicas
Estatísticas básicas de atividade do usuário básica
Neste relatório, são exibidas as estatísticas relacionadas às ações dos usuários em um canal. É possível filtrar o relatório para retornar somente os dados de um vídeo ou país específicos.
Estatísticas básicas de atividade do usuário para os estados nos EUA
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.
Atividade do usuário por país em períodos específicos
Neste relatório, são exibidas as estatísticas relacionadas às ações do usuário em um canal 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 relacionadas à atividade do usuário 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.
Neste relatório, são exibidas as estatísticas relacionadas à atividade do usuário em um canal para cada país. É possível filtrar o relatório para retornar somente os dados de um vídeo 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, é necessário definir o valor do parâmetro filters como country==US.
Atividade do usuário por cidade (<= 250 resultados)
Observação:neste 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, nesse relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Esse relatório fornece estatísticas de atividade do usuário por cidade.
Os relatórios de detalhes de 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 on demand?
O espectador estava inscrito no canal proprietário do vídeo?
Em qual produto do YouTube a visualização ocorreu?
Observação: a dimensão e o filtro liveOrOnDemand não podem ser usados com a métrica averageViewPercentage. Assim, cada uma das subseções a seguir lista dois relatórios. Um relatório é compatível com a dimensão e o filtro liveOrOnDemand, e o outro com a métrica averageViewPercentage.
Atividade do usuário por status de inscrição
Nesse relatório, são exibidas 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 para províncias
Neste relatório, são exibidas métricas de atividade do usuário para espectadores inscritos e não inscritos nos estados dos EUA ou no Distrito de Colúmbia. Este relatório suporta menos métricas do que o anterior.
Detalhes de reprodução com dimensão de tempo opcional
A dimensão de tempo (dia ou mês) é opcional para esses relatórios porque, independentemente disso, você precisa usar os parâmetros de solicitação startDate e endDate para especificar o período que o relatório abrangerá. A dimensão, se presente, indica que você quer que os dados do relatório sejam agregados por dia, mês etc.
Detalhes de reprodução com dimensão de tempo opcional e estatísticas liveOrOnDemand
Esse relatório fornece estatísticas detalhadas de reprodução para intervalos de tempo específicos. Ele aceita a dimensão e o filtro liveOrOnDemand.
Detalhes de reprodução com dimensão de tempo opcional e métrica averageViewPercentage
Esse relatório fornece estatísticas detalhadas de reprodução para intervalos de tempo específicos. Ele é compatível com a métrica averageViewPercentage.
O relatório a seguir é semelhante ao anterior. Ele adiciona suporte para a métrica averageViewPercentage, mas não aceita liveOrOnDemand como uma dimensão ou um filtro.
Detalhes de reprodução por província com estatísticas liveOrOnDemand
Este relatório fornece estatísticas detalhadas de reprodução para os estados dos EUA e o Distrito de Colúmbia. Ele aceita a dimensão e o filtro liveOrOnDemand.
O relatório a seguir é semelhante ao anterior. Ele adiciona suporte para a métrica averageViewPercentage, mas não aceita liveOrOnDemand como uma dimensão ou um filtro.
Observação:neste 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, nesse relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Neste relatório, são exibidos os players de vídeo incorporados por meio dos quais foi gerado o maior número de visualizações ou o maior tempo de visualização para os vídeos de um canal.
Neste relatório, são agregadas as estatísticas de visualização com base na forma como os espectadores chegaram ao conteúdo de seu vídeo. Por exemplo, nele é identificado o número de visualizações originadas em uma pesquisa no Google ou em um link para um vídeo relacionado.
Observação:neste 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, nesse relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Neste relatório, são agregadas as estatísticas de visualização com base nos referenciadores por meio dos quais foi gerado o maior número de visualizações para o conteúdo do canal. 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 listará os tipos de anúncios que geraram mais visualizações ou tempo de visualização para o conteúdo do canal.
Nota: este relatório é compatível apenas com origens do tráfego específicas. Por exemplo, a origem de tráfego NO_LINK_EMBEDDED não tem detalhes adicionais e, portanto, não suporta este relatório. Consulte a definição de insightTrafficSourceType para mais detalhes sobre quais origens de tráfego são compatíveis com esse relatório.
Tipo de dispositivo e sistema operacional
Tipo de dispositivo
Neste relatório, são agregadas as estatísticas de visualização com base na forma como os espectadores chegaram ao conteúdo de seu vídeo. Por exemplo, 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, 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.
Você pode usar filtros para garantir que o relatório contenha apenas dados de viewerPercentage para um valor (ou combinação de valores) para as dimensões de detalhes de reprodução.
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 de manter o público. A dimensão elapsedVideoTimeRatio mede o tempo decorrido do vídeo para os valores de métrica correspondentes. As métricas audienceWatchRatio e relativeRetentionPerformance fornecem duas medições que mostram a eficiência do vídeo em reter o público. O primeiro é um valor absoluto, enquanto o segundo mostra o desempenho do vídeo em relação a outros vídeos do YouTube de duração semelhante.
Observação: os relatórios de retenção de público não são compatíveis com a capacidade de especificar uma lista de valores separados por vírgulas para o filtro video; o valor precisa especificar um único ID do vídeo.
Observação:esses relatórios exigem que você defina o parâmetro maxResults com um valor inteiro de 200 ou menos. Antes de 1o de janeiro de 2013, os dados estão disponíveis somente para os 10 vídeos principais. Diferentemente da maioria dos outros relatórios, neste relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Principais vídeos com filtros regionais opcionais (<= 200 resultados)
Esse relatório lista os principais vídeos do canal. O relatório pode ser filtrado para listar os principais vídeos por país, continente ou subContinent.
Vídeos mais acessados por estado (<= 200 resultados)
Neste relatório, são listados os vídeos mais acessados em um estado específico nos 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.
Vídeos mais acessados para espectadores inscritos ou não(<= 200 resultados)
Esse relatório lista os principais vídeos do canal para espectadores inscritos ou não. O relatório pode ser filtrado para listar os principais vídeos por país, continente ou subContinent. O relatório anterior permitia recuperar os principais vídeos em um determinado estado nos EUA para espectadores inscritos ou não, mas suporta menos métricas do que este.
Principais vídeos por produto do YouTube (<= 200 resultados)
Esse relatório lista os principais vídeos do canal e oferece suporte a filtros geográficos e de detalhes de reprodução. Este relatório é semelhante ao anterior, mas oferece suporte a menos métricas e inclui suporte para o filtro youtubeProduct.
Os relatórios de playlists contêm métricas relacionadas às atividades do usuário relacionadas aos vídeos nas playlists do proprietário do canal. Há duas versões desses relatórios disponíveis e, para cada relatório disponível, as seções a seguir contêm uma descrição de cada uma delas:
A guia Recomendados em cada seção descreve o formato de solicitação de API preferido para recuperar o relatório correspondente. Os relatórios recomendados são compatíveis com um conjunto expandido de métricas
que inclui métricas de vídeo agregadas e
métricas na playlist. Este formato de solicitação não usa a dimensão isCurated.
A guia Usando isCurated em cada seção descreve um formato de solicitação de API mais antigo em que a dimensão isCurated é obrigatória. Esses relatórios são compatíveis somente com
métricas na playlist. O uso da dimensão isCurated foi suspenso em todos os relatórios. A nota de aviso abaixo explica o cronograma de descontinuação.
A observação 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
Elas fornecem métricas de atividade do usuário e de impressões que são agregadas para todos os vídeos
na playlist que também pertencem ao canal proprietário dela. As métricas para vídeos
pertencentes a outros canais não são calculadas na agregação. Como resultado, se um canal criar uma
playlist que contenha somente vídeos de outros canais, os relatórios dessas playlists não
fornecerão 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 as visualizações de todos os vídeos da playlist, independentemente do canal, mas
contam apenas as visualizações que ocorreram no contexto da playlist.
Este relatório apresenta estatísticas relacionadas às interações dos usuários com os vídeos nas
playlists do canal. É possível filtrar o relatório para retornar somente os dados de uma playlist específica.
Este relatório apresenta estatísticas relacionadas às interações dos usuários com os vídeos nas
playlists do canal. É possível filtrar o relatório para retornar somente os dados de uma playlist específica.
Este relatório mostra estatísticas de atividade de playlists para os estados dos EUA e o Distrito de Colúmbia.
Para esse relatório, é necessário filtrar os resultados para retornar dados somente dos Estados Unidos.
Observação:neste 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, nesse relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Esse relatório identifica os players de vídeo incorporados que geraram o maior número de visualizações ou tempo de visualização dos vídeos nas playlists do canal.
Nele, são agregadas as estatísticas de visualização com base em como os espectadores chegaram ao conteúdo da playlist.
Por exemplo, ele identifica o número de visualizações originadas de uma pesquisa no Google.
Observação:neste 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, nesse relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Neste relatório, são agregadas as estatísticas de visualização com base nos referenciadores que geraram o maior número de visualizações para os vídeos nas playlists do canal. Os referenciadores são categorizados por tipo de origem de tráfego, e a definição da dimensão insightTrafficSourceDetail identifica as origens para as quais o relatório está disponível.
Por exemplo, se você definir o filtro insightTrafficSourceType como ADVERTISING, o relatório listará os tipos de anúncios que geraram mais visualizações ou tempo de visualização para as playlists do canal.
Nota: este relatório é compatível apenas com origens do tráfego específicas. Por exemplo, a origem de tráfego NO_LINK_EMBEDDED não tem detalhes adicionais e, portanto, não suporta este relatório. Consulte a definição de insightTrafficSourceType para mais detalhes sobre quais origens de tráfego são compatíveis com esse relatório.
Tipo de dispositivo e sistema operacional
Tipo de dispositivo
Neste relatório, são agregadas as estatísticas de visualização com base em como os espectadores chegaram aos vídeos das suas playlists. Por exemplo, 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 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, identifica quantas visualizações ocorreram em tablets Android ou computadores 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, um relatório que usa a dimensão subscribedStatus retorna dados de viewerPercentage que somam 100% das visualizações inscritas eviewerPercentage dos dados das visualizações canceladas, somando até 100% para as visualizações canceladas. O valor total de todos os campos viewerPercentage do relatório é de 200%.
É possível usar filtros para garantir que o relatório contenha apenas dados de viewerPercentage para um valor das dimensões subscribedStatus.
Playlists mais acessadas
Observação:esses relatórios exigem que você defina o parâmetro maxResults com um valor inteiro de 200 ou menos. Antes de 1o de janeiro de 2013, os dados estão disponíveis somente para as 10 playlists principais. Diferentemente da maioria dos outros relatórios, neste relatório também é necessário especificar um valor para o parâmetro de solicitação sort.
Esse relatório lista as principais playlists do canal 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 concede acesso ao escopo https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Os relatórios de desempenho de anúncios fornecem métricas com base em impressões para anúncios exibidos durante reproduções de vídeo. 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 desempenho de anúncios baseados em impressão são:
Além disso, alguns relatórios de vídeo são compatíveis com as seguintes métricas de desempenho de anúncios com base em reprodução. Entretanto, essas métricas não estão incluídas nos relatórios de desempenho dos anúncios.
