Reports: Query

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

Esse método permite recuperar vários relatórios diferentes do Google Analytics. Cada solicitação usa parâmetros de consulta para especificar um ID do canal ou proprietário do conteúdo, uma data de início, uma data de término e pelo menos uma métrica. Também é possível 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 única de valores de dimensão.
  • Filtros são valores de dimensões que especificam os dados que serão recuperados. Por exemplo, você pode recuperar dados de um país, um vídeo ou um grupo de vídeos específicos.

Observação: os relatórios do proprietário do conteúdo são acessíveis apenas para 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. Este escopo fornece acesso às métricas de atividade do usuário e às métricas estimadas de receita e 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 o conteúdo associado no YouTube. 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 da API para recuperar relatórios de consulta. Os parâmetros de consulta padrão listados na tabela também são opcionais e são 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 para os quais 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 acontecerá mesmo se os dados para algumas das métricas solicitadas estiverem disponíveis a partir de 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 de que 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 para um proprietário de conteúdo do YouTube, defina o valor de 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 YouTube Analytics métricas, como views ou likes,dislikes. Consulte a documentação relatórios de canais ou relatórios do proprietário do conteúdo para ver uma lista dos relatórios que você pode recuperar 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 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 com base nas taxas de câmbio, que são alteradas diariamente. Se nenhuma dessas métricas for solicitada, o parâmetro será ignorado.

O valor do parâmetro é um código ISO 4217 de três letras da lista de moedas abaixo. A API retornará um erro se uma moeda não suportada 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 dos relatórios de canal ou dos relatórios do proprietário do conteúdo para uma lista dos relatórios que você pode recuperar e as dimensões usadas nesses 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, mescle-os com ponto e vírgula (;) e a tabela de resultados retornada satisfará os 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.

Como 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 do vídeo, da playlist ou do canal para os quais 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 de determinados vídeos na Itália. O valor do parâmetro pode especificar até 500 IDs.

Ao especificar vários valores para o mesmo filtro, também é possível adicioná-lo à lista de dimensões especificada para a solicitação. Isso acontecerá mesmo que o filtro não esteja listado como uma dimensão compatível com um relatório específico. Se você adicionar o filtro à lista de dimensões, a API também usará os valores dele para agrupar os resultados.

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

Indica se a resposta da API precisa incluir o tempo de exibição dos canais e os dados de visualização do período anterior à vinculação dos proprietários ao proprietário do conteúdo. O valor padrão do parâmetro é 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 para vários canais e o valor do parâmetro for false, a resposta da API conterá dados com base na data de vinculação para cada respectivo 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 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 do usuário atual.
alt Esse parâmetro não é compatível com a versão 2 da API, que só oferece suporte a 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 de chamada JavaScript que lida com a resposta.
  • Usado em solicitações JSON-P JavaScript.
prettyPrint

Retorna uma resposta com recuos e quebras de linha.

  • Retornará a resposta em um formato legível se for true.
  • Valor padrão: true.
  • Quando o valor for false, o tamanho do payload da resposta pode ser reduzido, o que pode melhorar o desempenho em alguns ambientes.
quotaUser Este 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 Este 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 este 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 incluir suporte para outros métodos, as respostas da API para esses métodos podem 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, que são seguidas pelas métricas especificadas na solicitação de API. A ordem das dimensões e métricas corresponde à ordem na solicitação de API.

Por exemplo, se a solicitação de API contiver os parâmetros dimensions=ageGroup,gender&metrics=viewerPercentage, a resposta da API 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 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 separados por vírgula será igual à ordem das colunas listadas no campo columnHeaders.

Se nenhum dado estiver disponível para a consulta em questão, 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: as amostras de código a seguir podem não representar todas as linguagens de programação compatíveis. Consulte a documentação bibliotecas clientes para 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 autorizado no ano civil de 2017. A amostra usa a biblioteca de cliente JavaScript das APIs do Google.

Antes de executar esta amostra localmente pela primeira vez, é necessário configurar as 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 projeto.
  3. Na parte superior da página Credenciais, selecione a guia Tela de consentimento 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 OAuth.
  5. Selecione o tipo de aplicativo "Web".
  6. No campo "Origens JavaScript autorizadas", insira o URL que servirá de base para 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 autorizado" 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á colocar no exemplo de código.

Em seguida, salve a amostra em um arquivo local. No exemplo, encontre a linha a seguir 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 o console de depuração. Você verá uma página que exibe 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, você vai ver as seguintes linhas impressas no console no 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 o projeto e se inseriu o ID do cliente no código conforme descrito acima.
  4. Clique no botão Executar para chamar a API. Você verá um objeto response exibido no console no 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 autorizado no ano civil de 2017. A amostra usa a biblioteca de cliente Python das APIs do Google.

Antes de executar esta amostra localmente pela primeira vez, é necessário configurar as 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 projeto.
  3. Na parte superior da página Credenciais, selecione a guia Tela de consentimento 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 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 para seu 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 no diretório de trabalho.
  2. No exemplo, atualize o valor da variável CLIENT_SECRETS_FILE para corresponder ao local do arquivo que você fez o 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 pode ser necessário copiar o URL de autenticação para uma janela do navegador. No 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 é mostrada 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'
  )

yt_analytics_v2.py

Confira!

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