Esta página lista os relatórios que os proprietários de canais podem recuperar com a API YouTube Analytics. Os relatórios de canal fornecem métricas de atividade do usuário para um canal especificado e medem coisas como exibições de vídeo, classificações e contagens de inscrições.
Como recuperar um relatório
Para recuperar um relatório de canal, é preciso definir o valor do parâmetro ids
na sua solicitação de API como um dos seguintes valores:
-
channel==MINE
: a API retorna dados para o canal do YouTube do usuário autenticado.
-
channel==CHANNEL_ID
: defina CHANNEL_ID
como o ID exclusivo do canal do canal para o qual você está recuperando dados. O usuário que autoriza a solicitação precisa ser o proprietário do canal.
No momento, o ID do canal é uma string que começa com as letras UC
, embora o formato esteja sujeito a mudanças. É possível encontrar o ID do seu canal na página de configurações avançadas da conta ou recuperar o ID do canal de forma programática usando o método YouTube Data API's channels.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:
Escopos |
https://www.googleapis.com/auth/yt-analytics.readonly |
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. |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
Visualizar os relatórios monetários do YouTube Analytics para seu conteúdo do YouTube. Este escopo fornece acesso às métricas de atividade do usuário e às métricas estimadas de receita e 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 o conteúdo associado no YouTube. 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, as métricas de receita estimada e desempenho do anúncio não são compatíveis com os 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 em 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 vários valores para um desses filtros, também poderá adicionar esse filtro à lista de dimensões especificada para a solicitação. Isso acontecerá 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 ver uma explicação completa sobre como filtrar os resultados da API para ver um valor específico ou um conjunto de valores.
Como entender as tabelas de relatório
Esta seção explica a formatação e a terminologia usada 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 os relatórios de playlist de canais com base no tempo:
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
A tabela contém duas linhas para dimensões, uma linha para métricas e quatro 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 de parâmetro dimensions
válidos para este relatório incluem:
dimensions=day
dimensions=7DayTotals,subscribedStatus
dimensions=30DayTotals,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 precisa usar exatamente 1. Nesse caso, o valor do 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 está documentado separadamente na documentação.
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 um valor obrigatório:
- Obrigatório: inclua o valor.
- Usar exatamente 1: você precisa incluir um valor do grupo.
- Usar um ou mais: é possível incluir qualquer um ou todos os valores do grupo, mas é preciso incluir pelo menos um.
- Estes termos significam que um valor é opcional:
- Opcional: você tem a opção de incluir o valor.
- Use 0 ou 1:você tem a opção de incluir um valor do grupo.
- Usar zero ou mais:você tem a opção de incluir qualquer 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.
Índice |
Dimensões: |
|
Métricas: |
Use um ou mais |
Não esqueça de usar os seguintes critérios: |
|
Filtros: |
|
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Por períodos
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.
Índice |
Dimensões: |
|
Métricas: |
Use um ou mais |
O que você deve fazer agora? |
|
Filtros: |
|
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Região do usuário
Atividade do usuário por país
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.
Índice |
Dimensões: |
|
Métricas: |
Use um ou mais |
Não esqueça de usar os seguintes critérios: |
|
Filtros: |
|
Atividade do usuário por província
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, você precisa definir o valor do parâmetro filters
como country==US
.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
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. Diferentemente da maioria dos outros relatórios, este relatório também exige a especificação de um valor para o parâmetro de solicitação sort
.
Este relatório mostra estatísticas de atividade do usuário por cidade.
Detalhes da reprodução
Os relatórios de detalhes da reprodução oferecem estatísticas relacionadas aos seguintes atributos de visualização:
- A visualização era de um vídeo ao vivo ou sob demanda?
- O espectador foi inscrito no canal que contém o vídeo?
- Em qual produto do YouTube a visualização ocorreu?
Observação:não é possível usar a dimensão e o filtro liveOrOnDemand com a métrica averageViewPercentage. Dessa forma, cada uma das subseções a seguir lista dois relatórios. Um relatório é compatível com a dimensão (e filtro) liveOrOnDemand, enquanto o outro é compatível com a métrica averageViewPercentage.
Atividade do usuário por status de assinante
Este relatório mostra 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 subcontinente.
Índice |
Dimensões: |
|
Métricas: |
Use um ou mais |
Os vídeos da franquia de livros na plataforma, em um dispositivo móvel, nas páginas do cadáver |
|
Filtros: |
|
Atividade do usuário por status de inscrição para províncias
Este relatório mostra métricas de atividade do usuário para espectadores inscritos e não inscritos nos estados dos EUA ou no Distrito de Colúmbia. O relatório é compatível com menos métricas do que o anterior.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
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 você precisa usar os parâmetros de solicitação startDate
e endDate
para especificar o período que o relatório abrange. A dimensão, se presente, indica que você quer que os dados do relatório sejam agregados por dia, mês etc.
Detalhes da reprodução com dimensões de tempo opcionais e estatísticas liveOrOnDemand.
Este relatório fornece estatísticas detalhadas da reprodução para intervalos de tempo específicos. Ele é compatível com a dimensão (e filtro) liveOrOnDemand.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da reprodução com dimensão de tempo opcional e métrica averageViewPercentage
Este relatório fornece estatísticas detalhadas da reprodução para intervalos de tempo específicos. Ele é compatível com a métrica averageViewPercentage.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da reprodução por país
Detalhes da reprodução por país com estatísticas de liveOrOnDemand
Esse relatório fornece estatísticas detalhadas da reprodução de acordo com o país. Ele é compatível com a dimensão (e filtro) liveOrOnDemand.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da reprodução por país com a métrica averageViewPercentage
O relatório a seguir é semelhante ao anterior. Adiciona suporte para a métrica averageViewPercentage, mas não oferece suporte a liveOrOnDemand como dimensão ou filtro.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da reprodução por província
Detalhes da reprodução por província com estatísticas de liveOrOnDemand
Este relatório mostra estatísticas detalhadas de reprodução de estados dos EUA e do Distrito de Colúmbia. Ele é compatível com a dimensão (e filtro) liveOrOnDemand.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da reprodução por província com a métrica averageViewPercentage
O relatório a seguir é semelhante ao anterior. Adiciona suporte para a métrica averageViewPercentage, mas não oferece suporte a liveOrOnDemand como dimensão ou filtro.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Locais de reprodução
Relatório do local de reprodução do vídeo
Neste relatório, são exibidas as estatísticas relacionadas ao tipo de página ou aplicativo em que ocorreram as reproduções do vídeo.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes do local da reprodução (<= 25 resultados)
Observação:neste relatório, é necessário definir o parâmetro maxResults
como um valor inteiro de 25
ou menos. Diferentemente da maioria dos outros relatórios, este relatório também exige a especificação de 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.
Origens de tráfego
Origem do tráfego
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da origem do tráfego (<= 25 resultados)
Observação:neste relatório, é necessário definir o parâmetro maxResults
como um valor inteiro de 25
ou menos. Diferentemente da maioria dos outros relatórios, este relatório também exige a especificação de 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 o maior número de visualizações ou o maior 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 é compatível com este relatório. Consulte a definição de insightTrafficSourceType para ver 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, ele identifica o número de visualizações que ocorreram em dispositivos móveis ou consoles de jogos.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Sistema operacional
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Sistema operacional e tipo de dispositivo
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Informações demográficas do espectador
Neste relatório, são agregadas as estatísticas de visualização com base na faixa etária e no gênero dos espectadores.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Retenção de público
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 como o vídeo retém 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 com duração semelhante.
Observação: os relatórios de retenção de público não podem especificar uma lista de valores separados por vírgulas para o filtro video
. O valor precisa especificar um único ID do vídeo.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Vídeos mais acessados
Observação:esses relatórios exigem que você defina o parâmetro maxResults
com um valor inteiro de 200
ou menos. Até 1o de janeiro de 2013, os dados eram disponibilizados apenas para os 10 principais vídeos. Diferentemente da maioria dos outros relatórios, eles também exigem que você especifique 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 subcontinente.
Principais vídeos 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.
Principais vídeos para espectadores inscritos ou não inscritos(<= 200 resultados)
Esse relatório lista os principais vídeos do canal para espectadores inscritos ou não inscritos. O relatório pode ser filtrado para listar os principais vídeos por país, continente ou subcontinente. O relatório anterior permite recuperar os principais vídeos em um estado específico nos EUA para espectadores inscritos ou não inscritos, mas aceita 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 detalhes de reprodução e filtros geográficos. Esse relatório é semelhante ao anterior, mas aceita menos métricas e adiciona suporte ao filtro youtubeProduct.
Principais vídeos com filtros de detalhes da reprodução (<= 200 resultados)
Esse relatório lista os principais vídeos do canal, filtrando por uma ou todas as dimensões de detalhes da reprodução: liveOrOnDemand, subscribedStatus e youtubeProduct. Diferentemente do relatório anterior, ele é compatível com o filtro liveOrOnDemand e não com a métrica averageViewPercentage.
Relatórios de playlists
Estatísticas básicas
Este relatório mostra as estatísticas relacionadas às interações dos usuários com as playlists de um canal. É possível filtrar o relatório para retornar somente os dados de uma playlist ou país específico.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Por períodos
Este relatório mostra as estatísticas relacionadas às interações dos usuários com as playlists de um canal. É possível filtrar o relatório para retornar somente os dados de uma playlist ou país específico.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Região do usuário
Atividade da playlist por país
Este relatório mostra as estatísticas relacionadas às interações dos usuários com as playlists de um canal. É possível filtrar o relatório para retornar somente os dados de uma playlist específica, de um grupo de playlists ou do país.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Atividade da playlist por província
Este relatório mostra estatísticas de atividade da playlist para estados dos EUA e para o Distrito de Colúmbia. Para esse relatório, inclua country==US
no valor do parâmetro filters
.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Locais de reprodução
Este relatório fornece estatísticas relacionadas ao tipo de página ou aplicativo em que as reproduções da playlist ocorreram.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes do local da reprodução (<= 25 resultados)
Observação:neste relatório, é necessário definir o parâmetro maxResults
como um valor inteiro de 25
ou menos. Diferentemente da maioria dos outros relatórios, este relatório também exige a especificação de 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 para as playlists de um canal.
Origens de tráfego
Esse relatório agrega estatísticas de visualização com base na maneira como os espectadores alcançaram o conteúdo da playlist. Por exemplo, ele identifica o número de visualizações de uma pesquisa no Google.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Detalhes da origem do tráfego (<= 25 resultados)
Observação:neste relatório, é necessário definir o parâmetro maxResults
como um valor inteiro de 25
ou menos. Diferentemente da maioria dos outros relatórios, este relatório também exige a especificação de um valor para o parâmetro de solicitação sort
.
Esse relatório agrega estatísticas de visualização com base nos referenciadores que geraram o maior número de visualizações para as 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 de tráfego 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 o maior número de visualizações ou de 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 é compatível com este relatório. Consulte a definição de insightTrafficSourceType para ver detalhes sobre quais origens de tráfego são compatíveis com esse relatório.
Tipo de dispositivo e sistema operacional
Tipo de dispositivo
Esse relatório agrega estatísticas de visualização com base na maneira como os espectadores alcançaram 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.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Sistema operacional
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 da playlist que ocorreram em dispositivos Android ou no PlayStation.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Sistema operacional e tipo de dispositivo
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 da playlist que ocorreram em tablets Android ou em computadores Windows.
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
Informações demográficas do espectador
Índice |
Dimensões: |
|
Métricas: |
|
Filtros: |
|
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 mais acessadas. Diferentemente da maioria dos outros relatórios, eles também exigem que você especifique 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 desempenho 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 oferecem métricas com base em impressões para anúncios que foram exibidos durante as reproduções de vídeo. Essas métricas consideram 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 com base em impressões 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. No entanto, essas métricas não são incluídas nos relatórios de desempenho de anúncios.
Índice |
Dimensões: |
Obrigatório |
adType (link em inglês) |
Opcional |
dia |
|
Métricas: |
|
Filtros: |
|