Esta página foi traduzida pela API Cloud Translation.

YouTube Analytics API - Data Model

Com a API YouTube Analytics, você pode gerar relatórios personalizados com dados do YouTube Analytics. A API é compatível com relatórios para canais e proprietários de conteúdo. Os campos do 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.

Em um relatório, cada linha de dados tem uma combinação única de valores de dimensão. Sendo assim, as dimensões que você escolhe para um relatório determinam como o YouTube calcula os valores das métricas do relatório.
Métricas são medidas individuais relacionadas à atividade do usuário, desempenho de anúncios ou receita estimada. As métricas de atividade do usuário incluem métricas como contagens e classificações de exibições de vídeos (marcações "Gostei" e "Não gostei").

A API Analytics fornece parâmetros de filtragem e classificação, portanto, o aplicativo de chamada não precisa oferecer suporte a essas funções de forma nativa. 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 os parâmetros do relatório

Quando você solicita um relatório usando o método reports.query da API, ela 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 conterá dados. A resposta da API contém dados até o último dia especificado, em que todas as métricas da consulta estão disponíveis no momento da consulta.
O parâmetro metrics especifica as medidas que vão ser incluídas no relatório. Nos relatórios de canais, as métricas avaliam a atividade do usuário e incluem valores como visualizações e marcações "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 vão ser 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 as 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 channel. 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 um proprietário de 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 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 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. 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. 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ção e de tempo de exibição serão agrupadas por tipo de dispositivo durante todo o período coberto pelo relatório. Portanto, com esse valor, os dados do relatório respondem a perguntas como:
  - Quantas vezes os vídeos do canal foram vistos em dispositivos móveis entre 1o de junho de 2015 e 31 de julho de 2015?
  - Quantas vezes os vídeos do canal foram exibidos em consoles de jogos entre 1o de junho de 2015 e 31 de julho de 2015?
  O relatório vai conter o total de visualizações e o tempo de exibição de cada tipo de dispositivo.
- Definir o valor do parâmetro como day,deviceType significa que as contagens de visualização e de tempo de exibição serão calculadas por tipo de dispositivo para cada dia durante o período do relatório. Portanto, com esse valor, os dados do relatório respondem a perguntas como:
  - Quantas vezes os vídeos do canal foram vistos em dispositivos móveis em 1o de junho de 2015?
  - Quantas vezes os vídeos do canal foram vistos na televisão 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 é compatível com muitas opções de filtragem para explicar todas elas. Portanto, esses exemplos representam apenas uma fração dos relatórios que podem ser gerados.
- O proprietário do canal pode filtrar a solicitação para retornar valores somente 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 somente para um país específico. Quantas vezes os vídeos foram vistos no Canadá em cada dia do período do relatório?
- O proprietário do canal pode filtrar a solicitação para retornar valores somente para vídeos específicos. No entanto, o filtro de vídeo é compatível com 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 de video especificar vários valores, video 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 video na lista de dimensões, as métricas especificarão valores individuais para cada vídeo. Quantas vezes o vídeo XYZ foi visualizado em um console de jogos em 1o de junho de 2015?
  - Se o proprietário do canal não incluir video na lista de dimensões, as métricas especificarão os valores totais que abrangem todos os vídeos especificados. (Quantas vezes os vídeos ABC, DEF e XYZ foram vistos em um console de jogos em 1o de junho de 2015?)

Recuperar relatórios

Para recuperar 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 recuperar.

Consulte a documentação Relatórios de canal e Relatórios do proprietário do conteúdo para ver uma lista de relatórios compatíveis com a API. 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 do cabeçalho de uma resposta para determinar a ordem das colunas do relatório. Por exemplo, não presuma 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 do cabeçalho da resposta para determinar qual coluna contém esses dados.
Use a API YouTube Data para recuperar metadados adicionais dos recursos identificados em respostas da API YouTube Analytics. Conforme indicado nas Políticas para desenvolvedores dos serviços da API do YouTube (seções III.E.4.b a III.E.4.d), os clientes de 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 retorna métricas com base em cada vídeo. No entanto, os relatórios que agregam métricas de um conjunto de recursos ainda incluem métricas associadas a itens excluídos.

Por exemplo, suponha que um proprietário de 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 por vídeo no mesmo período.

Nesse caso, os números do primeiro relatório incluem visualizações de vídeos que depois foram excluídos porque o primeiro relatório contém agregações diárias. No entanto, o segundo relatório não inclui as visualizações associadas a itens excluídos, já que ele lista as visualizações para cada vídeo. Por isso, se o canal excluir vídeos durante o período coberto pelo relatório, a contagem total de visualizações diárias no primeiro relatório poderá ser maior do que a soma das contagens diárias de vídeos específicos do segundo.

Anonimização de dados

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

um vídeo ou canal tem tráfego limitado durante um período específico;

ou
você tiver selecionado um filtro ou dimensão, como origem de tráfego ou país, para os quais os valores não atinjam um determinado limite.

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

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

Neste exemplo, o primeiro relatório indica que o vídeo foi visto mil vezes. O segundo relatório indica apenas que o vídeo foi visualizado 500 vezes nos Estados Unidos e 498 vezes no Canadá. Sendo assim, há uma diferença entre as contagens totais de visualizações nos dois relatórios. O segundo relatório não mostra nenhuma indicação de que duas outras visualizações também ocorreram (ou que qualquer visualização ocorreu na França).

Os limites reais em que os dados são limitados 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 em que os espectadores estavam localizados, como países ou regiões. No entanto, os relatórios não aplicam limites geográficos a 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 e URLs de pesquisa que geram um número muito pequeno de visualizações não aparecerão nos relatórios, embora você ainda veja termos e URLs que levam muitas pessoas até 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 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.