API de relatórios principais — guia do desenvolvedor

Este documento explica como usar a API de relatórios principais para acessar dados do Google Analytics.

Introdução

A API de relatórios principais fornece acesso aos dados tabulares em relatórios padrão e personalizados do Google Analytics. Para acessar os dados, crie uma consulta que especifique: a vista da propriedade (perfil), as datas de início e término, e as dimensões e métricas que compõem os cabeçalhos das colunas na tabela. Essa consulta é enviada para a Core Reporting API, que retorna todos os dados na forma de uma tabela.

Se você estiver começando a usar a API, leia a Visão geral da API de relatórios principais para ver uma introdução sobre o propósito da API de relatórios principais e dos dados que ela fornece.

Antes de começar

Este guia demonstra como acessar a Google Analytics API usando as linguagens de programação Java, Python, PHP e JavaScript.

  • Leia a página Bibliotecas cliente para ver uma lista completa de bibliotecas cliente específicas de linguagens de programação que funcionam com a API.
  • Leia o Guia de referência para acessar a API sem uma biblioteca cliente.

Cada biblioteca cliente fornece um único objeto de serviço de análise para acessar todos os dados da API de relatórios principais. Para criar o objeto de serviço, normalmente é necessário seguir estas etapas:

  1. Registre seu aplicativo no console de APIs do Google.
  2. Autorize o acesso aos dados do Google Analytics.
  3. Crie um objeto de serviço "Analytics".

Se você não tiver concluído essas etapas, pare e leia o Tutorial de apresentação da Google Analytics API. Ele orienta você sobre as etapas iniciais de criação de um aplicativo da Google Analytics API. Depois de concluir as etapas, você poderá usar este guia para executar tarefas reais.

O snippet de código a seguir contém uma variável para armazenar um objeto de serviço autorizado.

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

A biblioteca de PHP retorna todos os resultados da API como uma matriz associativa. Para retornar objetos reais, você pode chamar o método useObject cliente, conforme demonstrado no exemplo acima.

JavaScript

<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
  // Handle all the authorization work.
  // Read Hello Analytics Tutorial for details.
  gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>

A primeira tag do script carrega a biblioteca JavaScript da API do Google. Uma vez carregado, loadLib é executado para carregar a classe de serviço de análise. Quando concluído, o objeto gapi.client.analytics deve existir no DOM e estar pronto para ser usado para consultar a API de relatórios principais.

Assim que criar um objeto de serviço de análise, você estará pronto para fazer solicitações à API de relatórios principais.

Observação: o objeto de serviço de análise também pode ser usado para acessar a API de gerenciamento.

Visão geral

Um aplicativo que usa a API de relatórios principais geralmente segue duas etapas:

  • Consultar a API de relatórios principais
  • Trabalhar com os resultados da API

Vejamos como elas funcionam.

Consultar a API de relatórios principais

Criar uma consulta da API de relatórios principais

O objeto de serviço de análise contém um método para criar uma consulta da API de relatórios principais.

Cada consulta da API de relatórios principais contém um conjunto de parâmetros que especificam quais dados devem ser retornados.

Um dos parâmetros de consulta mais importantes é o ids ou o ID da tabela. Ele especifica de qual Vista (perfil) do Google Analytics os dados devem ser recuperados. O valor está no formato ga:xxx, onde xxx é o ID da Vista (perfil).

Java

Get apiQuery = analytics.data().ga()
    .get(tableId,                  // Table Id.
        "2012-01-01",              // Start date.
        "2012-01-15",              // End date.
        "ga:sessions")               // Metrics.
    .setDimensions("ga:source,ga:keyword")
    .setSort("-ga:sessions,ga:source")
    .setFilters("ga:medium==organic")
    .setMaxResults(25);

Python

api_query = service.data().ga().get(
    ids=TABLE_ID,
    start_date='2012-01-01',
    end_date='2012-01-15',
    metrics='ga:sessions',
    dimensions='ga:source,ga:keyword',
    sort='-ga:sessions,ga:source',
    filters='ga:medium==organic',
    max_results='25')

PHP

private function queryCoreReportingApi() {
  $optParams = array(
      'dimensions' => 'ga:source,ga:keyword',
      'sort' => '-ga:sessions,ga:source',
      'filters' => 'ga:medium==organic',
      'max-results' => '25');

  return $service->data_ga->get(
      TABLE_ID,
      '2010-01-01',
      '2010-01-15',
      'ga:sessions',
      $optParams);
}

Nesta biblioteca, o método get não só cria uma consulta da API de relatórios principais, mas também executa a solicitação para a API.

JavaScript

function makeApiCall() {
  var apiQuery = gapi.client.analytics.data.ga.get({
    'ids': TABLE_ID,
    'start-date': '2010-01-01',
    'end-date': '2010-01-15',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:source,ga:keyword',
    'sort': '-ga:sessions,ga:source',
    'filters': 'ga:medium==organic',
    'max-results': 25
  });
  // ...
}

Neste exemplo, a função makeApiCall é chamada assim que a biblioteca cliente JavaScript é carregada. Internamente, a função cria uma nova consulta da Google Analytics API e armazena o objeto na variável apiQuery.

Há uma listagem completa de todos os parâmetros de consulta e o que eles fazem disponível no Guia de referência da API de relatórios principais. Além disso, os parâmetros de dimensão e métrica permitem especificar quais dados devem ser recuperados do Google Analytics. A lista completa pode ser encontrada na página de referência de dimensões e métricas.

Como fazer uma solicitação de dados da API de relatórios principais

Depois de definir uma consulta, chame o método execute para enviar a consulta para os servidores do Google Analytics.

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

Se você preferir acessar a resposta original da API, use o método executeUnparsed():

HttpResponse response = apiQuery.executeUnparsed();

Python

try:
  results = get_api_query(service).execute()
  print_results(results)

except TypeError, error:
  # Handle errors in constructing a query.
  print ('There was an error in constructing your query : %s' % error)

except HttpError, error:
  # Handle API service errors.
  print ('There was an API error : %s : %s' %
         (error.resp.status, error._get_reason()))

PHP

  try {
    $results = queryCoreReportingApi();
    // Success. Do something cool!

  } catch (apiServiceException $e) {
    // Handle API service exceptions.
    $error = $e->getMessage();
  }

JavaScript

function makeApiCall() {
  // ...

  apiQuery.execute(handleCoreReportingResults);
}

function handleCoreReportingResults(results) {
  if (!results.error) {
    // Success. Do something cool!
  } else {
    alert('There was an error: ' + results.message);
  }
}

Este exemplo segue a etapa anterior, em que uma consulta da API de relatórios principais foi criada. Nesta etapa, a consulta é executada. O parâmetro do método execute é uma referência a uma função de retorno que é executada assim que os dados são retornados da API.

Quando a API retorna com os resultados, a função de retorno é executada, e os dados da API são transmitidos. Se ocorrer um erro, os resultados conterão uma propriedade chamada error.

Neste exemplo, é feita uma verificação para ver se error existe ou se a API retornou com êxito.

Se a consulta for bem-sucedida, a API retornará os dados solicitados. Se ocorrer algum erro, a API retornará um código de status específico e uma mensagem descrevendo o erro. Todos os aplicativos devem capturar e gerenciar os erros corretamente.

Trabalho com os resultados da API

Se a consulta da API de relatórios principais for bem-sucedida, a API retornará dados de relatórios do Google Analytics, bem como outras informações relacionadas sobre os dados.

Dados de relatórios do Google Analytics

Os principais dados retornados da API podem ser imaginados como uma tabela com dois tipos principais de dados:

  • O cabeçalho que descreve os tipos de valores de cada coluna
  • As linhas de dados da tabela

Dados do cabeçalho da coluna

Cada resposta da API contém um campo de cabeçalho da coluna que representa as informações do cabeçalho da tabela. O campo é uma lista (ou uma matriz) de objetos, na qual cada objeto descreve o tipo de dados da coluna. A ordem das colunas é: dimensões e métricas, na mesma ordem especificada na consulta original.

Java

private void printColumnHeaders(GaData gaData) {
 System.out.println("Column Headers:");

 for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
   System.out.println("Column Name: " + header.getName());
   System.out.println("Column Type: " + header.getColumnType());
   System.out.println("Column Data Type: " + header.getDataType());
 }
}

Python

def print_column_headers():
  headers = results.get('columnHeaders')

  for header in headers:
    # Print Dimension or Metric name.
    print 'Column name = %s' % header.get('name'))
    print 'Column Type = %s' % header.get('columnType')
    print 'Column Data Type = %s' % header.get('dataType')

PHP

private function printColumnHeaders(&results) {
  $html = '';
  $headers = $results->getColumnHeaders();

  foreach ($headers as $header) {
    $html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;

  print $html;
}

JavaScript

function printColumnHeaders(results) {
  var output = [];

  for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
    output.push(
        'Name        = ', header.name, '\n',
        'Column Type = ', header.columnType, '\n',
        'Data Type   = ', header.dataType, '\n'
    );
  }

  alert(output.join(''));
}

Dados de linha

Os principais dados retornados da API são retornados como uma List de strings bidimensional. A lista externa representa todas as linhas de dados. Cada lista interna representa uma única linha, em que a ordem das células em uma linha é a mesma dos campos do objeto de cabeçalho da coluna descrito acima.

Como os dados em cada célula são retornados como uma string, o campo DataType de cada objeto de cabeçalho da coluna é particularmente útil, pois pode ser usado para analisar os valores de string em um tipo apropriado. Consulte a resposta da API de metadados para todos os tipos de dados possíveis.

Os exemplos a seguir mostram os cabeçalhos e as linhas da tabela.

Java

private void printDataTable(GaData gaData) {
 if (gaData.getTotalResults() > 0) {
   System.out.println("Data Table:");

   // Print the column names.
   for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
     System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
   }
   System.out.println();

   // Print the rows of data.
   for (List<String> rowValues : gaData.getRows()) {
     for (String value : rowValues) {
       System.out.format("%-32s", value);
     }
     System.out.println();
   }
 } else {
   System.out.println("No Results Found");
 }

Python

def print_data_table(results):
  # Print headers.
  output = []
  for header in results.get('columnHeaders'):
    output.append('%30s' % header.get('name'))
  print ''.join(output)

  # Print rows.
  if results.get('rows', []):
    for row in results.get('rows'):
      output = []
      for cell in row:
        output.append('%30s' % cell)
      print ''.join(output)
  else:
    print 'No Results Found'

PHP

private function printDataTable(&$results) {
  if (count($results->getRows()) > 0) {
    $table .= '<table>';

    // Print headers.
    $table .= '<tr>';

    foreach ($results->getColumnHeaders() as $header) {
      $table .= '<th>' . $header->name . '</th>';
    }
    $table .= '</tr>';

    // Print table rows.
    foreach ($results->getRows() as $row) {
      $table .= '<tr>';
        foreach ($row as $cell) {
          $table .= '<td>'
                 . htmlspecialchars($cell, ENT_NOQUOTES)
                 . '</td>';
        }
      $table .= '</tr>';
    }
    $table .= '</table>';

  } else {
    $table .= '<p>No Results Found.</p>';
  }
  print $table;
}

JavaScript

function printRows(results) {
  output = [];

  if (results.rows && results.rows.length) {
    var table = ['<table>'];

    // Put headers in table.
    table.push('<tr>');
    for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
      table.push('<th>', header.name, '</th>');
    }
    table.push('</tr>');

    // Put cells in table.
    for (var i = 0, row; row = results.rows[i]; ++i) {
      table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
    }
    table.push('</table>');

    output.push(table.join(''));
  } else {
    output.push('<p>No Results Found</p>');
  }

  alert(output.join(''));
}

Informações do relatório

Além dos principais dados da tabela, os dados retornados da API contêm algumas informações de alto nível sobre a resposta. Você pode visualizá-las usando:

Java

private void printResponseInfo(GaData gaData) {
  System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
  System.out.println("Kind: " + gaData.getKind());
  System.out.println("ID:" + gaData.getId());
  System.out.println("Self link: " + gaData.getSelfLink());
}

Python

def print_response_info(results):
  print 'Contains Sampled Data = %s' % results.get('containsSampledData')
  print 'Kind                  = %s' % results.get('kind')
  print 'ID                    = %s' % results.get('id')
  print 'Self Link             = %s' % results.get('selfLink')

PHP

private function printReportInfo(&$results) {
  $html = <<<HTML
  <pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind                  = {$results->getKind()}
ID                    = {$results->getId()}
Self Link             = {$results->getSelfLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printReportInfo(results) {
  var output = [];

  output.push(
      'Contains Sampled Data  = ', results.containsSampledData, '\n',
      'Kind                   = ', results.kind, '\n',
      'ID                     = ', results.id, '\n',
      'Self Link              = ', results.selfLink, '\n');

  alert(output.join(''));
}

O campo containsSampledData é importante porque descreve se foi feito algum tipo de amostragem da resposta da API. A amostragem pode afetar os resultados dos seus dados e é um motivo comum pelo qual os valores retornados da API não correspondem à interface da Web. Consulte o guia do conceito Amostragem para mais detalhes.

Informações da vista da propriedade (perfil)

Cada resposta contém um conjunto de parâmetros que indicam a conta, a propriedade da Web e a vista da propriedade (perfil) às quais esses dados pertencem.

Java

private void printProfileInfo(GaData gaData) {
  GaDataProfileInfo profileInfo = gaData.getProfileInfo();

  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Python

def print_profile_info(result):

  info = results.get('profileInfo')
  print 'Account Id          = %s' % info.get('accountId')
  print 'Web Property Id     = %s' % info.get('webPropertyId')
  print 'Web Property Id     = %s' % info.get('internalWebPropertyId')
  print 'View (Profile) Id   = %s' % info.get('profileId')
  print 'Table Id            = %s' % info.get('tableId')
  print 'View (Profile) Name = %s' % info.get('profileName')

PHP

private function printProfileInformation(&$results) {
  $profileInfo = $results->getProfileInfo();

  $html = <<<HTML
<pre>
Account ID               = {$profileInfo->getAccountId()}
Web Property ID          = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID               = {$profileInfo->getProfileId()}
Table ID                 = {$profileInfo->getTableId()}
Profile Name             = {$profileInfo->getProfileName()}
</pre>
HTML;

  print $html;
}

JavaScript

function printProfileInfo(results) {
  var output = [];

  var info = results.profileInfo;
  output.push(

      'Account Id          = ', info.accountId, '\n',
      'Web Property Id     = ', info.webPropertyId, '\n',
      'View (Profile) Id   = ', info.profileId, '\n',
      'Table Id            = ', info.tableId, '\n',
      'View (Profile) Name = ', info.profileName);

  alert(output.join(''));
}

Cada um desses IDs corresponde a várias entidades na hierarquia da API de gerenciamento. Você pode usar esses IDs para formar consultas da API de gerenciamento e ver informações de configuração adicionais sobre a vista da propriedade (perfil). Por exemplo, você pode consultar o conjunto de metas da API de gerenciamento para ver quais metas estão ativas junto com seus nomes de meta configurados.

Informações da consulta

Cada resposta da Core Reporting API contém um objeto que contém todos os valores de parâmetro de consulta usados para criar a resposta.

Java

private void printQueryInfo(GaData gaData) {
  GaDataQuery query = gaData.getQuery();

  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics()); // List
  System.out.println("Dimensions: " + query.getDimensions());
  System.out.println("Sort: " + query.getSort()); // List
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Python

def print_query_info(results):
  query = results.get('query')
  for key, value in query.iteritems():
    print '%s = %s' % (key, value)

PHP

private function printQueryParameters(&$results) {
  $query = $results->getQuery();

  $html = '<pre>';
  foreach ($query as $paramName => $value) {
    $html .= "$paramName = $value\n";
  }
  $html .= '</pre>';

  print $html;
}

JavaScript

function printQuery(results) {
  output = [];

  for (var key in results.query) {
    output.push(key, ' = ', results.query[key], '\n');
  }

  alert(output.join(''));
}

Os parâmetros metrics e sort são retornados como valores em uma lista, enquanto os outros parâmetros são retornados como strings.

Informações de paginação

Qualquer solicitação da API de relatórios principais pode corresponder a centenas de milhares de linhas de dados do Google Analytics. A API de relatórios principais retorna apenas um subconjunto em um determinado momento, o qual pode se referir a uma única página de dados. Você pode usar os campos de paginação para recuperar todas as páginas de dados.

Java

private void printPaginationInfo(GaData gaData) {
  System.out.println("Items Per Page: " + gaData.getItemsPerPage());
  System.out.println("Total Results: " + gaData.getTotalResults());
  System.out.println("Previous Link: " + gaData.getPreviousLink());
  System.out.println("Next Link: " + gaData.getNextLink());
}

Python

def print_pagination_info(results):
  print 'Items per page = %s' % results.get('itemsPerPage')
  print 'Total Results  = %s' % results.get('totalResults')
  print 'Previous Link  = %s' % results.get('previousLink')
  print 'Next Link      = %s' % results.get('nextLink')

PHP

private function getPaginationInfo(&$results) {
  $html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results  = {$results->getTotalResults()}
Previous Link  = {$results->getPreviousLink()}
Next Link      = {$results->getNextLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printPaginationInfo(results) {
  var output = [];

  output.push(
      'Items Per Page = ', results.itemsPerPage, '\n',
      'Total Results  = ', results.totalResults, '\n',
      'Previous Link  = ', results.previousLink, '\n',
      'Next Link      = ', results.nextLink, '\n');

  alert(output.join(''));
}

O campo totalResults representa o número total de linhas de dados correspondentes à sua consulta no Google Analytics. Ele pode ser maior que o número real de linhas retornadas em uma única página da resposta. O campo itemsPerPage representa o número de linhas retornadas nessa página.

Os parâmetros previousLink e nextLink estarão presentes apenas se existir uma página anterior ou seguinte. Confira esses links para ver se mais páginas de dados podem ser recuperadas da API de relatórios principais.

Totais de todos os resultados

Como mencionado na seção de informações paginação acima, uma consulta para a API de relatórios principais pode corresponder a várias linhas de dados no Google Analytics, mas retorna apenas um subconjunto de dados. Os valores totais das métricas de todas as linhas correspondentes são retornados no objeto totalsForAllResults. Esses dados são úteis para calcular médias.

Java

private void printTotalsForAllResults(GaData gaData) {
  Map totalsMap = gaData.getTotalsForAllResults();

  for (Map.Entry entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Python

def print_totals_for_all_results(results):
  totals = results.get('totalsForAllResults')

  for metric_name, metric_total in totals.iteritems():
    print 'Metric Name  = %s' % metric_name
    print 'Metric Total = %s' % metric_total

PHP

private function printTotalsForAllResults(&$results) {
  $totals = $results->getTotalsForAllResults();

  foreach ($totals as $metricName => $metricTotal) {
    $html .= "Metric Name  = $metricName\n";
    $html .= "Metric Total = $metricTotal";
  }

  print $html;
}

JavaScript

function printTotalsForAllResults(results) {
  var output = [];

  var totals = results.totalsForAllResults;
  for (metricName in totals) {
    output.push(
        'Metric Name  = ', metricName, '\n',
        'Metric Total = ', totals[metricName], '\n');
  }

  alert(output.join(''));
}

Amostras de trabalho

Para ver as amostras de trabalho completas, confira o exemplo da API de relatórios principais no diretório de amostras de cada biblioteca cliente.

Java

Biblioteca cliente de Java da API do Google Amostra da API de relatórios principais

Python

Biblioteca cliente de Python da API do Google Amostra da API de relatórios principais

PHP

Biblioteca cliente de PHP da API do Google Amostra da API de relatórios principais

JavaScript

Biblioteca cliente de JavaScript da API do Google Amostra da API de relatórios principais

Origem de JavaScript