YouTube Analytics API - Data Model

Com a API YouTube Analytics, é possível 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 de relatório são caracterizados como dimensões ou métricas:

• As 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 única de valores de dimensão. Assim, as dimensões escolhidas para um relatório determinam como o YouTube calcula os valores das métricas nele.

• As 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 contagens de visualizações de vídeo e classificações (gostei e não gostei).

A API Analytics oferece 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.

Escolher parâmetros de relatório

Ao solicitar um relatório usando o método reports.query da API, a solicitação 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 gostei. Algumas métricas também medem a performance 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 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 denúncia

Por exemplo, suponha que o proprietário de um canal queira extrair 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 etc.

• 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 é compatível com as métricas views e estimatedMinutesWatched. Por isso, 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. Dois deles são mostrados na lista a seguir, e um terceiro é discutido na explicação do valor do parâmetro filters mais adiante nesta seção.

  • Definir o valor do parâmetro como deviceType significa que as contagens de visualizações e de tempo de exibição serão agrupadas por tipo de dispositivo durante todo o período abrangido 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 assistidos em dispositivos móveis entre 1º de junho e 31 de julho de 2015?
    • Quantas vezes os vídeos do canal foram assistidos em consoles de videogame entre 1º de junho de 2015 e 31 de julho de 2015?

    O relatório vai conter uma visão geral e uma contagem do 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 de 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 assistidos em dispositivos móveis em 1º de junho de 2015?
    • Quantas vezes os vídeos do canal foram assistidos em TVs 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 muitas opções de filtragem para explicar todas elas. Portanto, estes 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 vídeo aceita uma lista de valores separados por vírgulas. Portanto, o relatório pode conter dados de vários vídeos.

    Além disso, se o filtro vídeo especificar vários valores, vídeo também poderá ser especificado como uma dimensão. Isso significa que o parâmetro dimensions também é compatível com os 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 assistido 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 assistidos em um console de jogos em 1º de junho de 2015?)

Como recuperar relatórios

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

Consulte a documentação de relatórios do canal e relatórios do proprietário do conteúdo para conferir uma lista de relatórios compatíveis com a API. Cada definição de relatório identifica os valores permitidos 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á a primeira métrica retornada em uma resposta só porque é a primeira métrica listada na descrição de um 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 dos recursos identificados nas respostas da API YouTube Analytics. Conforme observado nas Políticas para desenvolvedores de serviços da API 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 vai mais aparecer em uma resposta da API que retorna 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 determinado período. O segundo relatório lista o total de visualizações diárias de cada vídeo no mesmo período.

Nesse caso, os números do primeiro relatório incluem visualizações de vídeos que foram excluídos posteriormente, porque o primeiro relatório contém agregações diárias. No entanto, o segundo relatório não inclui visualizações associadas a itens excluídos porque ele lista as visualizações de cada 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 pode ser maior do que a soma das visualizações diárias específicas do vídeo no segundo relatório.

Anonimização de dados

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

1. um vídeo ou canal tem tráfego limitado durante um período especificado;

   ou

2. você selecionou um filtro ou uma dimensão, como origem do tráfego ou país, para os quais os valores não atingem 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 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.

Neste 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 a contagem total de visualizações nos dois relatórios. O segundo relatório não mostraria que outras duas visualizações também ocorreram ou que o vídeo foi visto 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 seguintes dados 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 onde 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 geraram visualizações dos seus vídeos. Por exemplo, termos de pesquisa e URLs que geram um número muito pequeno de visualizações não aparecem nos relatórios, mas você ainda vai encontrar termos e URLs que atraem 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.

Uso de cota

Cada solicitação de API feita conta como uma unidade da sua cota de uso da API. Os limites de cota podem ser vistos no painel Cotas do console de APIs do Google.