Reports: Query

Importante:as solicitações de API para esse método agora exigem acesso ao escopo https://www.googleapis.com/auth/youtube.readonly.

Com esse método, você pode recuperar vários relatórios do Google Analytics. Cada solicitação usa parâmetros de consulta para especificar um ID de canal ou proprietário do conteúdo, uma data de início, uma data de término e pelo menos uma métrica. Você também pode fornecer parâmetros de consulta adicionais, como dimensões, filtros e instruções de classificação.

  • Métricas são medidas individuais de atividade do usuário, como exibições ou classificações de vídeo (gostei e não gostei).
  • Dimensões são critérios comuns usados ​​para dados agregados, como a data em que ocorreu a atividade do usuário ou o país em que os usuários estavam localizad. Em um relatório, cada linha de dados tem uma combinação exclusiva de valores de dimensão.
  • Filtros são valores de dimensões que especificam os dados que serão recuperados. Por exemplo, é possível recuperar dados de um país, um vídeo específico ou um grupo de vídeos.

Observação: os relatórios do proprietário do conteúdo são acessíveis apenas a parceiros de conteúdo do YouTube que participam do Programa de Parcerias do YouTube.

Casos de uso comuns

Solicitação

Solicitação HTTP

GET https://youtubeanalytics.googleapis.com/v2/reports

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

Parâmetros

As tabelas a seguir listam parâmetros de consulta obrigatórios e opcionais para solicitações de API recuperarem relatórios de consulta. Os parâmetros de consulta padrão listados na tabela também são opcionais e são aceitos por muitas APIs do Google.

Parâmetros
Parâmetros obrigatórios
endDate string
A data de término para buscar dados do YouTube Analytics. O valor precisa estar no formato YYYY-MM-DD.

A resposta da API contém dados até o último dia para o qual todas as métricas na consulta estão disponíveis no momento da consulta. Por exemplo, se a solicitação especificar uma data de término em 5 de julho de 2017, e os valores de todas as métricas solicitadas estiverem disponíveis somente até 3 de julho de 2017, essa será a última data em que os dados serão incluídos na resposta. Isso é válido mesmo que os dados de algumas das métricas solicitadas estejam disponíveis para 4 de julho de 2017.
Observação:na versão 1 da API, esse parâmetro era chamado de end-date.
ids string
Identifica o canal do YouTube ou o proprietário do conteúdo para o qual você está recuperando dados de YouTube Analytics.

  • Para solicitar dados para um canal do YouTube, defina o valor do parâmetro ids como channel==MINE ou channel==CHANNEL_ID, em que CHANNEL_ID identifica o canal do YouTube do usuário autenticado no momento.
  • Para solicitar dados a um proprietário de conteúdo do YouTube, defina o valor do parâmetro ids como contentOwner==OWNER_NAME, em que OWNER_NAME é o content owner ID para o usuário.

metrics string
Uma lista separada por vírgulas de métricas YouTube Analytics, como views ou likes,dislikes. Consulte a documentação dos relatórios de canal ou relatórios do proprietário do conteúdo para obter uma lista dos relatórios que você pode recuperar e as métricas disponíveis em cada relatório. O documento Métricas contém definições de todas as métricas.
startDate string
A data de início para buscar dados do YouTube Analytics. O valor precisa estar no formato YYYY-MM-DD.
Observação:na versão 1 da API, esse parâmetro era chamado de start-date.
Parâmetros opcionais
currency string
A moeda que a API vai usar para especificar as seguintes métricas de receita estimada: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Os valores que a API retorna para essas métricas são estimativas calculadas usando as taxas de câmbio que mudam diariamente. Se nenhuma dessas métricas for solicitada, o parâmetro será ignorado.

O valor do parâmetro é um código de moeda ISO 4217 de três letras que aparece na lista abaixo. A API retorna um erro se uma moeda não compatível for especificada. O valor padrão é USD.
dimensions string
Uma lista separada por vírgulas de dimensões do YouTube Analytics, como video ou ageGroup,gender. Consulte a documentação de relatórios de canal ou relatórios do proprietário do conteúdo para uma lista dos relatórios que você pode recuperar e as dimensões usadas para esses relatórios. O documento Dimensões contém definições de todas as dimensões.
filters string
Uma lista de filtros que precisam ser aplicados ao recuperar dados de YouTube Analytics. A documentação de relatórios de canal e relatórios do proprietário do conteúdo identifica as dimensões que podem ser usadas para filtrar cada relatório, e o documento Dimensões define essas dimensões.

Se uma solicitação usar vários filtros, junte-os com um ponto e vírgula (;), e a tabela de resultados retornada atenderá aos dois filtros. Por exemplo, um valor de parâmetro filters de video==dMH0bHeiRNg;country==IT restringe o conjunto de resultados para incluir dados para determinado vídeo na Itália.

Especificar vários valores para um filtro

A API permite especificar diversos valores para os filtros video, playlist e channel. Para isso, especifique uma lista separada de IDs de vídeo, playlist ou canal para a qual a resposta da API deve ser filtrada. Por exemplo, um valor de parâmetro filters de video==pd1FJh59zxQ,Zhawgd0REhA;country==IT restringe o conjunto de resultados para incluir dados para os vídeos fornecidos na Itália. O valor do parâmetro pode especificar até 500 IDs.

Ao especificar diversos valores para o mesmo filtro, também é possível adicioná-lo à 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. Se você adicionar o filtro à lista de dimensões, a API também usará os valores do filtro para agrupar os resultados.

Por exemplo, suponha que você recupere o relatório de origem do tráfego de um canal, que agrega estatísticas de visualização com base na maneira como os espectadores chegaram ao conteúdo de vídeo do canal. Suponha também que a solicitação do parâmetro filters da sua solicitação identifique uma lista de 10 vídeos para os quais os dados precisam ser retornados.
  • Se você adicionar video ao valor do parâmetro dimensions, a resposta da API fornecerá estatísticas separadas de origem de tráfego para cada um dos 10 vídeos.
  • Se você não adicionar video ao valor do parâmetro dimensions, a resposta da API agregará as estatísticas de origem de tráfego de todos os 10 vídeos.
includeHistoricalChannelData boolean
Observação:esse parâmetro só se aplica a relatórios do proprietário do conteúdo.

Indica se a resposta da API deve incluir o tempo de exibição dos canais e os dados de visualização do período anterior a quando os canais foram vinculados ao proprietário do conteúdo. O valor de parâmetro padrão é false, o que significa que a resposta da API inclui apenas o tempo de exibição e os dados de visualização das datas em que os canais foram vinculados ao proprietário do conteúdo.

É importante lembrar que canais diferentes podem ter sido vinculados a um proprietário de conteúdo em datas diferentes. Se a solicitação de API estiver recuperando dados de vários canais e o valor do parâmetro for false, a resposta da API conterá dados com base na data de vinculação de cada canal. Se o valor do parâmetro for true, a resposta da API vai conter dados correspondentes às datas especificadas na solicitação de API.
Observação:na versão 1 da API, esse parâmetro era chamado de include-historical-channel-data.
maxResults integer
O número máximo de linhas a serem incluídas na resposta.
Observação:na versão 1 da API, esse parâmetro era chamado de max-results.
sort string
Uma lista separada por vírgulas de dimensões ou métricas que determinam a ordem de classificação dos dados do YouTube Analytics. Por padrão, a ordem de classificação é crescente. O prefixo - causa uma ordem de classificação decrescente.
startIndex integer
O índice baseado em 1 da primeira entidade a ser recuperada. O valor padrão é 1. Use esse parâmetro como um mecanismo de paginação junto com o parâmetro max-results.
Observação:na versão 1 da API, esse parâmetro era chamado de start-index.
Parâmetros padrão
access_token Token OAuth 2.0 para o usuário atual.
alt Este parâmetro não é compatível com a versão 2 da API, que só é compatível com respostas JSON.O formato de dados para a resposta da API.
  • Valores válidos: json, csv
  • Valor padrão: json
callback Função de retorno de chamada.
  • Nome da função de retorno de chamada JavaScript que lida com a resposta.
  • Usado em solicitações JavaScript JSON-P.
prettyPrint

Retorna uma resposta com recuos e quebras de linha.

  • Retorna a resposta em um formato legível se true.
  • Valor padrão: true.
  • Quando for false, o tamanho do payload da resposta poderá ser reduzido, o que talvez leve a um melhor desempenho em alguns ambientes.
quotaUser Esse parâmetro era compatível com a versão 1 da API, que foi descontinuada. Esse parâmetro não é compatível com a versão 2 da API.
userIp Esse parâmetro era compatível com a versão 1 da API, que foi descontinuada. Esse parâmetro não é compatível com a versão 2 da API.

Corpo da solicitação

Não envie um corpo de solicitação ao chamar esse método.

Resposta

Conforme observado na definição do parâmetro alt, a API pode retornar respostas no formato JSON ou CSV. Informações sobre o corpo da resposta para cada tipo são mostradas abaixo:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Propriedades
kind string
Esse valor especifica o tipo de dados incluído na resposta da API. Para o método query, o valor da propriedade kind será youtubeAnalytics#resultTable. No entanto, se a API adicionar suporte para outros métodos, as respostas da API para esses métodos poderão introduzir outros valores de propriedade kind.
columnHeaders[] list
Esse valor especifica informações sobre os dados retornados nos campos rows. Cada item na lista de columnHeaders identifica um campo retornado no valor rows, que contém uma lista de dados separados por vírgulas.

A lista de columnHeaders começa com as dimensões especificadas na solicitação de API, que são seguidas pelas métricas especificadas. A ordem das dimensões e métricas corresponde à ordem na solicitação de API.

Por exemplo, se a solicitação de API tiver os parâmetros dimensions=ageGroup,gender&metrics=viewerPercentage, a resposta da API vai retornar colunas nesta ordem: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Nome da dimensão ou métrica.
columnHeaders[].columnType string
O tipo da coluna (DIMENSION ou METRIC).
columnHeaders[].dataType string
O tipo dos dados na coluna (STRING, INTEGER, FLOAT etc.).
rows[] list
A lista contém todas as linhas da tabela de resultados. Cada item da lista é uma matriz que contém dados separados por vírgula que correspondem a uma única linha de dados. A ordem dos campos de dados delimitados por vírgulas corresponderá à ordem das colunas listadas no campo columnHeaders.

Se não houver dados disponíveis para determinada consulta, o elemento rows será omitido da resposta.

A resposta para uma consulta com a dimensão day não conterá linhas dos dias mais recentes.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Exemplos

Observação:os exemplos de código a seguir podem não representar todas as linguagens de programação compatíveis. Consulte a documentação das bibliotecas de cliente para ver uma lista das linguagens suportadas.

JavaScript

Este exemplo chama a API YouTube Analytics para recuperar visualizações diárias e outras métricas do canal do usuário que fez a autorização para o ano-calendário de 2017. O exemplo usa a biblioteca de cliente JavaScript das APIs do Google.

Antes de executar esta amostra localmente pela primeira vez, você precisa configurar credenciais de autorização para seu projeto:
  1. Crie ou selecione um projeto no Console de APIs do Google.
  2. Ative a API YouTube Analytics no seu projeto.
  3. Na parte superior da página Credenciais, selecione a guia Tela de permissão OAuth. Selecione um Endereço de e-mail, insira um Nome de produto se ainda não estiver definido e clique no botão Salvar.
  4. Na página Credenciais, clique no botão Criar credenciais e selecione ID do cliente do OAuth.
  5. Selecione o tipo de aplicativo da Web.
  6. No campo Origens JavaScript autorizadas, insira o URL que será usado para disponibilizar o exemplo de código. Por exemplo, é possível usar algo como http://localhost:8000 ou http://yourserver.example.com. É possível deixar o campo "URIs de redirecionamento autorizados" em branco.
  7. Clique no botão Criar para concluir a criação das credenciais.
  8. Antes de fechar a caixa de diálogo, copie o ID do cliente, que será colocado no exemplo de código.

Em seguida, salve o exemplo em um arquivo local. No exemplo, encontre a linha a seguir e substitua YOUR_CLIENT_ID pelo ID do cliente que você recebeu durante a configuração das credenciais de autorização.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Agora, está tudo pronto para testar o exemplo:

  1. Abra o arquivo local em um navegador da Web e o console de depuração no navegador. Você verá uma página com dois botões.
  2. Clique no botão Autorizar e carregar para iniciar o fluxo de autorização do usuário. Se você autorizar o app a recuperar os dados do seu canal, as seguintes linhas vão aparecer no console do navegador: 
    Sign-in successful
GAPI client loaded for API
  3. Se uma mensagem de erro for exibida em vez das linhas acima, verifique se você está carregando o script pelo URI de redirecionamento autorizado configurado para seu projeto e se colocou seu ID do cliente no código, conforme descrito acima.
  4. Clique no botão execute para chamar a API. Um objeto response vai aparecer no console do navegador. Nesse objeto, a propriedade result é mapeada para um objeto que contém os dados da API.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

Este exemplo chama a API YouTube Analytics para recuperar visualizações diárias e outras métricas do canal do usuário que fez a autorização para o ano-calendário de 2017. O exemplo usa a biblioteca de cliente das APIs do Google para Python.

Antes de executar esta amostra localmente pela primeira vez, você precisa configurar credenciais de autorização para seu projeto:
  1. Crie ou selecione um projeto no Console de APIs do Google.
  2. Ative a API YouTube Analytics no seu projeto.
  3. Na parte superior da página Credenciais, selecione a guia Tela de permissão OAuth. Selecione um Endereço de e-mail, insira um Nome de produto se ainda não estiver definido e clique no botão Salvar.
  4. Na página Credenciais, clique no botão Criar credenciais e selecione ID do cliente do OAuth.
  5. Selecione o tipo de aplicativo Outro, insira o nome "Guia de início rápido da API YouTube Analytics" e clique no botão "Criar".
  6. Clique em OK para dispensar a caixa de diálogo exibida.
  7. Clique no botão (Fazer o download do JSON) à direita do ID do cliente.
  8. Mova o arquivo salvo para o diretório de trabalho.

Também é necessário instalar a biblioteca de cliente de APIs do Google para Python e algumas bibliotecas adicionais:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Agora, está tudo pronto para testar o exemplo:

  1. Copie o exemplo de código abaixo no seu diretório de trabalho.
  2. No exemplo, atualize o valor da variável CLIENT_SECRETS_FILE para corresponder ao local do arquivo que você transferiu por download depois de configurar suas credenciais de autorização.
  3. Execute o exemplo de código em uma janela de terminal: 
    python yt_analytics_v2.py
  4. Siga o fluxo de autorização. O fluxo de autenticação pode ser carregado automaticamente no navegador, ou talvez seja necessário copiar o URL de autenticação em uma janela do navegador. Ao final do fluxo de autorização, se necessário, cole o código de autorização exibido no navegador na janela do terminal e clique em [return].
  5. A consulta de API é executada e a resposta JSON é enviada para a janela do terminal.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Confira!

Use o APIs Explorer para chamar essa API e conferir a solicitação e a resposta da API.