Reports: Query

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

Com esse método, é possível recuperar vários relatórios diferentes 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 outros parâmetros de consulta, 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 única 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 ou um grupo de vídeos específicos.

Observação:os relatórios de proprietários do conteúdo só podem ser acessados por 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 dá acesso a métricas de atividade do usuário e a métricas estimadas de receita e performance 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 grupo do YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Ver e gerenciar recursos do YouTube e conteúdo associado na plataforma. Na API YouTube Analytics, os proprietários de conteúdo usam esse escopo para gerenciar grupos e itens de grupo do YouTube Analytics.

Parâmetros

As tabelas a seguir listam os parâmetros de consulta obrigatórios e opcionais para solicitações de API que recuperam relatórios de consulta. Os parâmetros de consulta padrão listados na tabela também são opcionais e compatíveis com muitas APIs do Google.

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

A resposta da API contém dados até o último dia em que 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 de 5 de julho de 2017, e os valores de todas as métricas solicitadas estiverem disponíveis apenas 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 de conteúdo para quem você está recuperando dados de YouTube Analytics.

  • Para solicitar dados de 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 de um proprietário do conteúdo do YouTube, defina o valor do parâmetro ids como contentOwner==OWNER_NAME, em que OWNER_NAME é o content owner ID do usuário.

metrics string
Uma lista separada por vírgulas de métricas de YouTube Analytics, como views ou likes,dislikes. Consulte a documentação sobre relatórios do canal ou relatórios do proprietário do conteúdo para ver uma lista dos relatórios que podem ser recuperados e as métricas disponíveis em cada um deles. O documento Métricas contém definições de todas as métricas.
startDate string
A data de início para buscar dados de 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 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 da lista abaixo. A API retorna um erro se uma moeda não aceita 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 do canal ou relatórios do proprietário do conteúdo para ver uma lista dos relatórios que podem ser recuperados e as dimensões usadas neles. O documento Dimensões contém definições para todas as dimensões.
filters string
Uma lista de filtros que devem ser aplicados ao recuperar dados de YouTube Analytics. A documentação dos relatórios de canais e relatórios de proprietários de 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 vai 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 do vídeo especificado na Itália.

Especificar vários valores para um filtro

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

Ao especificar vários valores para o mesmo filtro, você também pode adicionar esse filtro à lista de dimensões que especificou para a solicitação. Isso é válido mesmo que o filtro não esteja listado como uma dimensão compatível para um determinado relatório. Se você adicionar o filtro à lista de dimensões, a API também usará os valores de filtro para agrupar os resultados.

Por exemplo, suponha que você recupere um relatório de origem do tráfego de um canal, que agrega estatísticas de visualização com base na maneira como os espectadores acessaram o conteúdo de vídeo do canal. Suponha também que o 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 vai 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 vai agregar as estatísticas de origem de tráfego de todos os 10 vídeos.
includeHistoricalChannelData boolean
Observação:esse parâmetro se aplica apenas a relatórios de proprietários de conteúdo.

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

É importante lembrar que diferentes canais podem ter sido vinculados a um proprietário do 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 vai 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 da 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 a ordem de classificação decrescente.
startIndex integer
O índice com base em 1 da primeira entidade a ser recuperada. O valor padrão é 1. Use esse parâmetro como um mecanismo de paginação 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 Esse parâmetro não é compatível com a versão 2 da API, que só aceita respostas JSON. O formato de dados da 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 JavaScript que trata a resposta.
  • Usado em solicitações JSON-P de JavaScript.
prettyPrint

Retorna uma resposta com recuos e quebras de linha.

  • Retornará a resposta em formato legível se for true.
  • Valor padrão: true.
  • Se for false, poderá reduzir o tamanho do payload da resposta, o que talvez melhore o desempenho em alguns ambientes.
quotaUser Esse parâmetro era compatível com a versão 1 da API, que agora está 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 agora está 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ídos na resposta da API. Para o método query, o valor da propriedade kind será youtubeAnalytics#resultTable. No entanto, se a API adicionar suporte a 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 columnHeaders identifica um campo retornado no valor rows, que contém uma lista de dados delimitados por vírgulas.

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

Por exemplo, se a solicitação da API contiver os parâmetros dimensions=ageGroup,gender&metrics=viewerPercentage, a resposta da API vai retornar colunas nesta ordem: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
O nome da dimensão ou métrica.
columnHeaders[].columnType string
O tipo da coluna (DIMENSION ou METRIC).
columnHeaders[].dataType string
O tipo de 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írgula vai corresponder à ordem das colunas listadas no campo columnHeaders.

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

A resposta de uma consulta com a dimensão day não vai 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 de linguagens compatíveis.

JavaScript

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

Antes de executar esta amostra localmente pela primeira vez, configure as credenciais de autorização do 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 de cima 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 "Aplicativo da Web".
  6. No campo "Origens JavaScript autorizadas", insira o URL de onde você vai veicular o exemplo de código. Por exemplo, você pode usar algo como http://localhost:8000 ou http://yourserver.example.com. Você pode 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 você precisará inserir no exemplo de código.

Em seguida, salve a amostra em um arquivo local. No exemplo, encontre a seguinte linha e substitua YOUR_CLIENT_ID pelo ID do cliente que você recebeu ao configurar suas credenciais de autorização.

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

Agora, você já pode testar a amostra:

  1. Abra o arquivo local em um navegador da Web e abra o console de depuração no navegador. Uma página com dois botões vai aparecer.
  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 serão impressas no console do navegador:
    Sign-in successful
    GAPI client loaded for API
  3. Se você vir uma mensagem de erro em vez das linhas acima, confirme se está carregando o script do URI de redirecionamento autorizado configurado para seu projeto e se inseriu o ID do cliente no código conforme descrito acima.
  4. Clique no botão Executar para chamar a API. Um objeto response será impresso 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>

Python

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

Antes de executar esta amostra localmente pela primeira vez, configure as credenciais de autorização do 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 de cima 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 "Início rápido da API YouTube Analytics" e clique no botão "Criar".
  6. Clique em OK para fechar a caixa de diálogo.
  7. Clique no botão (Fazer o download do JSON) à direita do ID do cliente.
  8. Mova o arquivo baixado para o diretório de trabalho.

Você também precisa instalar a biblioteca de cliente das 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, você já pode testar a amostra:

  1. Copie o exemplo de código abaixo para 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ê baixou 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 da API é executada, e a resposta JSON é gerada na 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'
  )

Confira!

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