O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

YouTube Analytics API - Data Model

A API YouTube Analytics permite gerar relatórios personalizados com dados do YouTube Analytics. A API oferece suporte a relatórios para canais e proprietários de conteúdo. Os campos do relatório são caracterizados como dimensões ou métricas:

Dimensões são critérios comuns usados para agregar dados, como a data em que uma ação ocorreu ou o país em que os usuários estavam localizados.

Em um relatório, cada linha de dados tem uma combinação exclusiva de valores de dimensão. Assim, as dimensões escolhidas para um relatório determinam como o YouTube calcula os valores das métricas nesse relatório.
Métricas são medições individuais relacionadas à atividade do usuário, ao desempenho do anúncio ou à receita estimada. As métricas de atividade do usuário incluem itens como contagens de visualizações e classificações de vídeos (cliques em "Gostei" e "Não gostei").

A API Analytics fornece parâmetros de filtragem e classificação. Assim, o aplicativo de chamada não precisa oferecer suporte nativo a essas funções. A API também permite recuperar dados de grupos do YouTube Analytics, em que um grupo é uma coleção personalizada de até 500 vídeos, playlists, canais ou recursos.

Como escolher parâmetros de relatório

Ao solicitar um relatório usando o método reports.query da API, a solicitação de API contém cinco parâmetros que determinam como os valores do relatório serão calculados:

Os parâmetros startDate e endDate especificam o período em que o relatório vai conter dados. A resposta da API contém dados até o último dia especificado em que todas as métricas na consulta estão disponíveis no momento da consulta.
O parâmetro metrics especifica as medições que serão incluídas no relatório. Nos relatórios de canais, as métricas medem a atividade do usuário e incluem valores como visualizações e cliques em "Gostei". Algumas métricas também medem o desempenho do anúncio ou a receita estimada.
O parâmetro dimensions explica como as métricas serão agrupadas.
O parâmetro filters explica como os dados do relatório serão filtrados. Por exemplo, em vez de retornar todos os dados de um canal, um relatório pode ser filtrado para conter apenas métricas de um determinado país, vídeo ou grupo de vídeos.

Observação:a API permite especificar vários valores para os filtros de vídeo, playlist e canal. Se você fizer isso, também poderá incluir esse filtro na lista de dimensões para que as métricas retornadas também sejam agrupadas por vídeo, playlist ou canal.

Exemplos de opções de relatórios

Por exemplo, suponha que o proprietário de um canal queira recuperar um relatório de tipo de dispositivo de vídeo para determinar quantas visualizações dos vídeos do canal ocorreram em dispositivos móveis, consoles de jogos, TVs e assim por diante.

O proprietário do canal define o parâmetro startDate como 2015-06-01 e o parâmetro endDate como 2015-07-31. Com base nesses valores, o relatório vai conter dados de um período de dois meses.
O relatório de tipo de dispositivo oferece suporte às métricas de visualizações e estimatedMinutesWatched. Portanto, o proprietário do canal define o parâmetro metrics como views,estimatedMinutesWatched.
Para o parâmetro dimensions, o proprietário do canal tem várias opções. Duas delas são mostradas na lista a seguir, e uma terceira é discutida na explicação do valor de parâmetro filters mais adiante nesta seção.
- Definir o valor do parâmetro como deviceType significa que as contagens de visualizações e tempo de exibição serão agrupadas por tipo de dispositivo para todo o período coberto pelo relatório. Assim, com esse valor, os dados do relatório vão responder a perguntas como:
  - Quantas vezes os vídeos do canal foram visualizados em dispositivos móveis entre 1º de junho de 2015 e 31 de julho de 2015?
  - Quantas vezes os vídeos do canal foram visualizados em consoles de jogos entre 1º de junho de 2015 e 31 de julho de 2015?
  O relatório vai conter uma contagem total de visualizações e tempo de exibição para cada tipo de dispositivo.
- Definir o valor do parâmetro como day,deviceType significa que as contagens de visualizações e tempo de exibição serão calculadas por tipo de dispositivo para cada dia durante o período do relatório. Assim, com esse valor, os dados do relatório vão responder a perguntas como:
  - Quantas vezes os vídeos do canal foram visualizados em dispositivos móveis em 1º de junho de 2015?
  - Quantas vezes os vídeos do canal foram visualizados em televisões em 14 de julho de 2015?
Por fim, o parâmetro filters permite que o proprietário do canal restrinja o relatório para incluir apenas dados que correspondam a valores de filtro específicos. O relatório oferece suporte a muitas opções de filtragem para explicar todas elas. Portanto, esses exemplos representam apenas uma fração dos relatórios que você pode gerar.
- O proprietário do canal pode filtrar a solicitação para retornar valores apenas para o sistema operacional Android. (Quantas visualizações ocorreram em dispositivos móveis Android durante o período do relatório?)
- O proprietário do canal pode filtrar a solicitação para retornar valores apenas de um país específico. (Quantas vezes os vídeos foram visualizados no Canadá em cada dia do período do relatório?)
- O proprietário do canal pode filtrar a solicitação para retornar valores apenas de vídeos específicos. No entanto, o filtro de vídeo oferece suporte a uma lista de valores separados por vírgulas. Portanto, o relatório pode conter dados de muitos vídeos.
  
  Além disso, se o filtro de vídeo especificar vários valores, então o vídeo também poderá ser especificado como uma dimensão. Isso significa que o dimensions parâmetro também oferece suporte aos valores deviceType,video e day,deviceType,video.
  - Se o proprietário do canal incluir vídeo na lista de dimensões, as métricas vão especificar valores individuais para cada vídeo. (Quantas vezes o vídeo XYZ foi visualizado em um console de jogos em 1º de junho de 2015?)
  - Se o proprietário do canal não incluir vídeo na lista de dimensões, as métricas vão especificar valores totais que abrangem todos os vídeos especificados. (Quantas vezes os vídeos ABC, DEF e XYZ foram visualizados em um console de jogos em 1º de junho de 2015?)

Atualização e latência de dados

Embora a API YouTube Analytics ofereça suporte a consultas segmentadas, os dados de análise subjacentes não são em tempo real. O processamento de dados normalmente introduz uma latência de 48 a 72 horas. Portanto, as respostas da API não contêm dados dos dias mais recentes, e o endDate do relatório inclui apenas dados até o último dia em que todas as métricas solicitadas foram totalmente processadas.

Devido à latência dos dados, você pode notar discrepâncias entre os dados retornados pela API e as métricas em tempo real visíveis no YouTube Studio. Se o aplicativo exigir estatísticas em tempo real para vídeos individuais , como contagens de visualizações, cliques em "Gostei" ou comentários atuais, use o método videos.list da API YouTube Data em vez da API YouTube Analytics.

Como recuperar relatórios

Para recuperar um relatório, envie uma solicitação GET autorizada para o método reports.query da API, especificando os parâmetros que definem o relatório que você quer recuperar.

Consulte a documentação de relatórios de canais e relatórios de proprietários de conteúdo para conferir uma lista de relatórios que a API oferece suporte. Cada definição de relatório identifica os valores que o relatório permite para os parâmetros metrics, dimensions e filters.

Práticas recomendadas

Os aplicativos que usam a API YouTube Analytics sempre precisam seguir estas práticas:

Use a linha de cabeçalho de uma resposta para determinar a ordem das colunas do relatório. Por exemplo, não suponha que visualizações serão a primeira métrica retornada em uma resposta apenas porque é a primeira métrica listada em uma descrição do relatório. Em vez disso, use a linha de cabeçalho da resposta para determinar qual coluna contém esses dados.
Use a API YouTube Data para recuperar metadados adicionais de recursos identificados nas respostas da API YouTube Analytics. Conforme observado nas Políticas do desenvolvedor de serviços de APIs do YouTube (seções III.E.4.b a III.E.4.d), os clientes da API precisam excluir ou atualizar os metadados de recursos armazenados dessa API após 30 dias.

Métricas agregadas e itens excluídos

As respostas da API YouTube Analytics não contêm detalhamentos de métricas para itens excluídos. Por exemplo, se o proprietário de um canal excluir um vídeo, ele não será mais listado em uma resposta da API que retorne métricas de vídeo por vídeo. No entanto, os relatórios que agregam métricas para um conjunto de recursos ainda incluem métricas associadas a itens excluídos.

Por exemplo, suponha que o proprietário de um canal recupere dois relatórios. O primeiro relatório lista o total de visualizações diárias de todos os vídeos do canal em um período específico. O segundo relatório lista o total de visualizações diárias de vídeo por vídeo no mesmo período.

Nesse caso, os números no primeiro relatório vão incluir visualizações de vídeos que foram excluídos posteriormente, porque o primeiro relatório contém agregados diários. No entanto, o segundo relatório não vai incluir visualizações associadas a itens excluídos porque o segundo relatório lista visualizações de vídeo por vídeo. Como resultado, se o canal excluiu vídeos durante o período coberto pelo relatório, o total de visualizações diárias informado no primeiro relatório poderá ser maior do que a soma das contagens de visualizações diárias e específicas de vídeo no segundo relatório.

Anonimização de dados

Alguns dados do YouTube Analytics são limitados quando as métricas não atendem a um determinado limite. Isso pode acontecer em vários relatórios. Na prática, isso significa que um relatório pode não conter todos os seus dados (ou nenhum deles) se:

um vídeo ou canal tiver tráfego limitado durante um período especificado,

ou
você selecionou um filtro ou uma dimensão, como origem de tráfego ou país, para os quais os valores não atendem a um determinado limite.

Nos casos em que os dados são limitados, pode haver uma diferença entre os totais informados nos diferentes relatórios, dependendo de como esses relatórios agregam os dados.

Por exemplo, suponha que o proprietário de um canal recupere dois relatórios. O primeiro relatório lista o total de visualizações de um vídeo específico, e o segundo relatório lista o total de visualizações desse vídeo por país. Durante o período especificado, vamos dizer que o vídeo tenha sido visualizado 1.000 vezes, sendo que 500 das visualizações ocorreram nos Estados Unidos, 498 no Canadá e duas na França.

Nesse exemplo, o primeiro relatório indicaria que o vídeo foi visualizado 1.000 vezes. O segundo relatório indicaria apenas que o vídeo foi visualizado 500 vezes nos Estados Unidos e 498 vezes no Canadá. Portanto, haveria uma diferença entre o total de visualizações nos dois relatórios. O segundo relatório não conteria nenhuma indicação de que outras duas visualizações também ocorreram (ou que alguma visualização ocorreu na França).

Os limites reais para os dados não são publicados e estão sujeitos a mudanças a critério do YouTube.

Tipos de dados limitados

Os dados a seguir podem ser limitados nos relatórios do YouTube Analytics:

Dados demográficos, como idade e gênero.
Dados geográficos, incluindo métricas ou dimensões relacionadas aos países ou regiões em que os espectadores estavam localizados, como os países ou regiões deles. No entanto, os relatórios não aplicam limites geográficos às métricas de receita.
Métricas relacionadas a origens de tráfego específicas, como termos de pesquisa ou URLs externos que levaram a visualizações dos seus vídeos. Por exemplo, termos de pesquisa e URLs que levam a um número muito pequeno de visualizações não vão aparecer nos relatórios, mas você ainda vai ver termos e URLs que geram muitos espectadores para seu conteúdo.

Consulte a Central de Ajuda do YouTube para mais informações sobre dados limitados nos relatórios do YouTube Analytics.

Utilização de cota

Cada solicitação de API que você faz conta como uma unidade da sua cota de uso da API. Os limites de cota ficam visíveis no painel "Cotas" do console de APIs do Google.