API de relatórios principais: guia de referência

Este documento fornece a referência completa para consulta e resposta da Core Reporting API versão 3.0.

Introdução

Consulte a Core Reporting API para encontrar dados de relatórios do Google Analytics. Cada consulta requer um código de vista (perfil), uma data de início e de término e pelo menos uma métrica. Você também pode fornecer parâmetros de consulta adicionais como dimensões, filtros e segmentos para refinar sua consulta. Consulte o Guia de visão geral para entender como todos esses conceitos funcionam juntos.

Solicitação

A API fornece um único método para solicitar dados:

analytics.data.ga.get()

Esse método é exposto em várias bibliotecas cliente e possui interfaces específicas de idiomas para definir os parâmetros de consulta.

Também é possível consultar a API como um ponto de extremidade REST-ful:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Cada parâmetro de consulta de URL especifica um parâmetro de consulta de API que deve obrigatoriamente ser codificado por URL.

Resumo dos parâmetros de consulta

A tabela a seguir resume todos os parâmetros de consulta aceitos pela Core Reporting API. Clique no nome de cada parâmetro para ver uma descrição detalhada.

Nome Valor Obrigatório Resumo
ids string sim O código único da tabela no formato ga:XXXX, em que XXXX é o código da vista (perfil) do Google Analytics para o qual a consulta recuperará os dados.
start-date string sim Data de início para a recuperação de dados do Google Analytics. As solicitações podem especificar uma data de início no formato YYYY-MM-DD ou como uma data relativa (por exemplo, today, yesterday ou NdaysAgo, em que N é um número inteiro positivo).
end-date string sim Data de término para a recuperação de dados do Google Analytics. A solicitação pode especificar uma data de término no formato YYYY-MM-DD ou como uma data relativa (por exemplo, today, yesterday ou NdaysAgo, em que N é um número inteiro positivo).
metrics string sim Uma lista de métricas separadas por vírgulas, como ga:sessions,ga:bounces.
dimensions string não Uma lista de dimensões separadas por vírgulas para seus dados do Google Analytics, como ga:browser,ga:city.
sort string não Uma lista de dimensões e métricas separadas por vírgulas que indica a ordem e a direção de classificação dos dados retornados.
filters string não Filtros de métrica ou dimensão que restringem os dados retornados para sua solicitação.
segment string não Segmenta os dados retornados para sua solicitação.
samplingLevel string não O nível de amostragem desejado. Valores permitidos:
  • DEFAULT: retorna uma resposta com um tamanho de amostra que equilibra velocidade e precisão.
  • FASTER: retorna uma resposta rápida com um tamanho de amostra menor.
  • HIGHER_PRECISION: retorna uma resposta mais precisa usando um tamanho de amostra grande, mas isso pode deixar a resposta mais lenta.
include-empty-rows boolean não Definido como "true" por padrão. Se definido como "false", as linhas em que todos os valores das métricas são zero serão omitidas da resposta.
start-index integer não Primeira linha de dados a serem recuperados, a partir de 1. Use esse parâmetro como um mecanismo de paginação juntamente com o parâmetro max-results.
max-results integer não Número máximo de linhas a serem incluídas na resposta.
output string não Tipo de saída desejado para os dados do Google Analytics retornados na resposta. Os valores aceitáveis são json e dataTable. Padrão: json.
fields string não Seletor que especifica um subconjunto de campos a serem incluídos na resposta.
prettyPrint string não Retorna uma resposta com recuos e quebras de linha. Padrão false.
userIp string não Especifica o endereço IP do usuário final para o qual a chamada da API está sendo feita. Usado para limitar o uso por IP.
quotaUser string não Alternativa a "userIp" quando o endereço IP do usuário é desconhecido.
access_token string não Uma maneira possível de fornecer um token OAuth 2.0.
callback string não Nome da função de retorno JavaScript que trata a resposta. Usado em solicitações JavaScript JSON-P.
key string não Usado para autorização OAuth 1.0a com a finalidade de especificar sua inscrição para receber cotas. Por exemplo: key=AldefliuhSFADSfasdfasdfASdf{/1.

Detalhes dos parâmetros de consulta

ids

ids=ga:12345
Obrigatório.
O ID exclusivo usado para recuperar os dados do Google Analytics. Esse ID é a concatenação do namespace ga: com o código da vista (perfil) do Google Analytics. Você pode recuperar o código da vista (perfil) usando o método analytics.management.profiles.list, que fornece o id no recurso de vista (perfil) na API Google Analytics Management.

start-date

start-date=2009-04-20
Obrigatório.
É necessário que todas as solicitações de dados do Google Analytics especifiquem um período. Se você não incluir os parâmetros start-date e end-date na solicitação, o servidor retornará um erro. Os valores de data podem ser de uma data específica, usando o padrão YYYY-MM-DD, ou relativos, usando o padrão today, yesterday ou NdaysAgo. Os valores precisam corresponder a [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
A start-date válida mais antiga é 2005-01-01. Não há restrições de limite superior para uma data de início.
As datas relativas são sempre relativas à data atual no momento da consulta e se baseiam no fuso horário da vista (perfil) especificada na consulta.

Exemplo de período para os últimos sete dias (a partir de ontem) usando datas relativas:

  &start-date=7daysAgo
  &end-date=yesterday

end-date

end-date=2009-05-20
Obrigatório.
É necessário que todas as solicitações de dados do Google Analytics especifiquem um período. Se você não incluir os parâmetros start-date e end-date na solicitação, o servidor retornará um erro. Os valores de data podem ser de uma data específica, usando o padrão YYYY-MM-DD, ou relativos, usando o padrão today, yesterday ou NdaysAgo. Os valores precisam corresponder a [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
A end-date válida mais antiga é 2005-01-01. Não há restrições de limite superior para uma end-date.
As datas relativas são sempre relativas à data atual no momento da consulta e se baseiam no fuso horário da vista (perfil) especificada na consulta.

Exemplo de período para os últimos 10 dias (a partir de hoje) usando datas relativas:

  &start-date=9daysAgo
  &end-date=today

dimensions

dimensions=ga:browser,ga:city
Opcional.
O parâmetro dimensions divide as métricas por critérios comuns. Por exemplo, por ga:browser ou ga:city. Embora você possa pedir o número total de exibições de páginas para seu site, pode ser mais interessante pedir o número de exibições de páginas divididas por navegador. Nesse caso, você verá o número de exibições de páginas do Firefox, Internet Explorer, Google Chrome e assim por diante.

Quando você usar dimensions em uma solicitação de dados, lembre-se das seguintes restrições:

  • Você pode fornecer no máximo sete dimensões em qualquer consulta.
  • Não é possível enviar uma consulta composta somente por dimensões: você precisa combinar qualquer dimensão solicitada com pelo menos uma métrica.
  • Somente determinadas dimensões podem ser consultadas na mesma consulta. Use a ferramenta de combinação válida na Referência de dimensões e métricas para ver quais dimensões podem ser usadas juntas.


metrics

metrics=ga:sessions,ga:bounces
Obrigatório.
As estatísticas agregadas da atividade do usuário para seu site, como cliques ou exibições de páginas. Se uma consulta não tem o parâmetro dimensions, as métricas retornadas fornecem valores agregados para o período solicitado, como exibições de páginas gerais ou o total de rejeições. No entanto, quando são solicitadas dimensões, os valores são segmentados por valor da dimensão. Por exemplo, ga:pageviews solicitada com ga:country retorna o total de exibições de páginas por país. Quando você solicitar métricas, lembre-se de que:
  • Todas as solicitações precisam fornecer pelo menos uma métrica. Uma solicitação não pode consistir apenas em dimensões.
  • Você pode fornecer no máximo 10 métricas para uma consulta.
  • A maioria das combinações de métricas de várias categorias podem ser usadas juntas, desde que nenhuma dimensão seja especificada.
  • Uma métrica pode ser usada em combinação com outras dimensões ou métricas, mas somente quando combinações válidas são aplicáveis a essa métrica. Consulte a Referência de dimensões e métricas para ver detalhes.


sort

sort=ga:country,ga:browser
Opcional.

Uma lista de dimensões e métricas que indica a ordem e a direção de classificação dos dados retornados.

  • A ordem de classificação é especificada pela ordem da esquerda para a direita das métricas e dimensões indicadas.
  • O padrão da direção de classificação é a ordem crescente. Tal direção pode ser alterada para a ordem decrescente com um sinal de subtração (-) como prefixo no campo solicitado.

Classificar os resultados de uma consulta permite fazer perguntas diferentes sobre seus dados. Por exemplo, para resolver a questão "Quais são meus principais países e quais navegadores eles usam mais?",você pode fazer uma consulta com o parâmetro a seguir. Ele classifica primeiro por ga:country e depois por ga:browser, ambos em ordem crescente:

sort=ga:country,ga:browser

Para responder a pergunta relacionada "Quais são meus principais navegadores e quais países mais os utilizam?",você pode fazer uma consulta com o parâmetro a seguir. Ele classifica primeiro por ga:browser e depois por ga:country, ambos em ordem crescente:
sort=ga:browser,ga:country

Quando você usar o parâmetro sort, lembre-se de que:

  • Classifique somente por valores de dimensões ou métricas que você usou nos parâmetros dimensions ou metrics. Se a solicitação for classificada em um campo que não é indicado no parâmetro de dimensões ou métricas, você receberá uma mensagem de erro.
  • Por padrão, as strings são classificadas em ordem alfabética crescente, na localidade en-US.
  • Por padrão, os números são classificados em ordem numérica crescente.
  • Por padrão, as datas são classificadas em ordem crescente por data.

filters

filters=ga:medium%3D%3Dreferral
Opcional.

O parâmetro da string de consulta filters restringe os dados retornados para sua solicitação. Para usar o parâmetro filters, forneça uma dimensão ou métrica para filtragem, seguida pela expressão de filtro. Por exemplo, a consulta a seguir solicita ga:pageviews e ga:browser para a vista (perfil) 12134, em que a dimensão ga:browser começa com a string Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

As consultas filtradas restringem as linhas que são (ou não) incluídas no resultado. Cada linha no resultado é testada com o filtro: se o filtro for correspondente, a linha será mantida. Caso contrário, ela será descartada.

  • Codificação de URL: as bibliotecas cliente da Google API codificam automaticamente os operadores de filtro.
  • Filtragem de dimensão: a filtragem acontece antes que qualquer dimensão seja agregada para que as métricas retornadas representem o total somente para as dimensões relevantes. No exemplo acima, o número de exibições de páginas representa apenas as exibições nas quais o Firefox é o navegador.
  • Filtragem de métricas: a filtragem de métricas acontece depois que as métricas são agregadas.
  • Combinações válidas: é possível filtrar uma dimensão ou métrica que não faz parte da consulta, desde que todas as dimensões/métricas da solicitação e o filtro sejam combinações válidas. Por exemplo, convém consultar uma lista de exibições de páginas com data, filtrando por determinado navegador. Consulte a Referência de dimensões e métricas para mais informações.

Sintaxe de filtro


Um único filtro usa o formulário:

ga:name operator expression

Nesta sintaxe:

  • name: o nome da dimensão ou da métrica a ser filtrada. Por exemplo: ga:pageviews é filtrado na métrica de exibições de páginas.
  • operator: define o tipo de correspondência de filtro a ser usado. Os operadores são específicos de dimensões ou métricas.
  • expression: indica os valores a serem incluídos ou excluídos dos resultados. As expressões usam a sintaxe de expressão regular.

Operadores de filtro


Há seis operadores de filtro para dimensões e seis para métricas. É necessário que os operadores sejam codificados por URL para que sejam incluídos em strings de consulta de URL.

Dica: use o Query Explorer de feed de dados para criar filtros que precisam de codificação de URL, pois o Query Explorer codifica automaticamente URLs que contêm strings e espaços.

Filtros de métrica
Operador Descrição Formulário codificado pelo URL Exemplos
== Igual a %3D%3D Retorna resultados nos quais o tempo na página é exatamente de 10 segundos:
filters=ga:timeOnPage%3D%3D10
!= Não é igual a !%3D Retorna resultados nos quais o tempo na página não é de 10 segundos:
filters=ga:timeOnPage!%3D10
> Maior que %3E Retorna resultados nos quais o tempo na página é estritamente maior que 10 segundos:
filters=ga:timeOnPage%3E10
< Menor que %3C Retorna resultados nos quais o tempo na página é estritamente menor que 10 segundos:
filters=ga:timeOnPage%3C10
>= Maior ou igual a %3E%3D Retorna resultados nos quais o tempo na página é igual a 10 segundos ou mais:
filters=ga:timeOnPage%3E%3D10
<= Menor ou igual a: %3C%3D Retorna resultados nos quais o tempo na página é menor ou igual a 10 segundos:
filters=ga:timeOnPage%3C%3D10

Filtros de dimensão
Operador Descrição Formulário codificado pelo URL Exemplo
== Correspondência exata %3D%3D Métricas agregadas nas quais a cidade é Irvine:
filters=ga:city%3D%3DIrvine
!= Não corresponde !%3D Métricas agregadas nas quais a cidade não é Irvine:
filters=ga:city!%3DIrvine
=@ Contém substring %3D@ Métricas agregadas nas quais a cidade contém York:
filters=ga:city%3D@York
!@ Não contém substring !@ Métricas agregadas nas quais a cidade não contém York:
filters=ga:city!@York
=~ Contém uma correspondência para a expressão regular %3D~ Métricas agregadas nas quais a cidade começa com Nova:
filters=ga:city%3D~%5ENew.*
%5E é o URL codificado a partir do caractere ^ que ancora um padrão ao início da string.
!~ Não corresponde à expressão regular !~ Métricas agregadas nas quais a cidade não começa com Nova:
filters=ga:city!~%5ENew.*

Expressões de filtro

Há algumas regras importantes para expressões de filtro:

  • Caracteres reservados pelo URL: é necessário que caracteres como & sejam codificados pelo URL da maneira habitual.
  • Caracteres reservados: o ponto e vírgula e a vírgula precisam ser separados pela barra invertida quando aparecem em uma expressão:
    • ponto e vírgula \;
    • vírgula \,
  • Expressões regulares: você também pode usar expressões regulares em expressões de filtro usando os operadores =~ e !~. A sintaxe delas é semelhante à das expressões regulares de Perl e contém estas regras adicionais:
    • Tamanho máximo de 128 caracteres: expressões regulares maiores que 128 caracteres resultam em um código de status 400 Bad Request retornado do servidor.
    • Distinção entre letras maiúsculas e minúsculas: a correspondência da expressão regular diferencia letras maiúsculas e minúsculas.

Combinação de filtros

Os filtros podem ser combinados usando a lógica booleana OR e AND. Desse modo, você pode estender com eficiência o limite de 128 caracteres de uma expressão de filtro.

OR

O operador OR é definido com uma vírgula (,). Ele tem precedência sobre o operador AND e NÃO pode ser usado para combinar dimensões e métricas na mesma expressão.

Exemplos: (cada um deles deve obrigatoriamente ser codificado por URL)

O país é (Estados Unidos OR Canadá):
ga:country==United%20States,ga:country==Canada

Usuários do Firefox em sistemas operacionais (Windows OR Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

O operador AND é definido com ponto e vírgula (;). Ele é precedido pelo operador OR e PODE ser usado para combinar dimensões e métricas na mesma expressão.

Exemplos: (cada um deles deve obrigatoriamente ser codificado por URL)

O país é Estados Unidos AND o navegador é Firefox:
ga:country==United%20States;ga:browser==Firefox

O país é Estados Unidos AND o idioma não começa com "en":
ga:country==United%20States;ga:language!~^en.*

O sistema operacional é (Windows OR Macintosh) AND o navegador é (Firefox OR Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

O país é Estados Unidos AND as sessões são maiores que 5:
ga:country==United%20States;ga:sessions>5



segment

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Opcional.

Para ver detalhes completos sobre como solicitar um segmento na Core Reporting API, consulte o Guia para desenvolvedores de segmentos.

Para uma visão geral conceitual dos segmentos, consulte Referência de recursos de segmentos e Segmentos na Central de Ajuda.

Dimensões e métricas permitidas nos segmentos.
Nem todas as dimensões e métricas podem ser usadas nos segmentos. Para ver quais dimensões e métricas são permitidas nos segmentos, acesse o Explorador de dimensões e métricas.


samplingLevel

samplingLevel=DEFAULT
Opcional.
Use esse parâmetro para definir o nível de amostragem (por exemplo, o número de sessões usadas para calcular o resultado) de uma consulta de relatórios. Os valores permitidos são consistentes com a interface da Web e incluem:
  • DEFAULT: retorna uma resposta com um tamanho de amostra que equilibra velocidade e precisão.
  • FASTER: retorna uma resposta rápida com um tamanho de amostra menor.
  • HIGHER_PRECISION: retorna uma resposta mais precisa usando um tamanho de amostra grande, mas isso pode deixar a resposta mais lenta.
Se não for fornecido, o nível de amostragem DEFAULT será usado.
Consulte a seção Amostragem para ver detalhes sobre como calcular a porcentagem de sessões que foram usadas para uma consulta.

include-empty-rows

include-empty-rows=true
Opcional.
Definido como "true" por padrão. Se definido como "false", as linhas em que todos os valores das métricas são zero serão omitidas da resposta. Por exemplo, se você incluir mais de uma métrica em uma consulta, as linhas só serão removidas se todos os valores das métricas forem zero. Isso pode ser útil ao fazer uma solicitação em que se estima que o número de linhas válidas seja bem menor que o de valores de dimensões esperados.

start-index

start-index=10
Opcional.
Se não for fornecido, o índice inicial será 1. Os índices de resultados baseiam-se em 1. Isto é, a primeira linha é a 1, não a 0. Use esse parâmetro como um mecanismo de paginação com o parâmetro max-results para situações em que totalResults exceder 10.000 e você quiser recuperar as linhas indexadas de 10.001 em diante.

max-results

max-results=100
Opcional.
Número máximo de linhas a serem incluídas nessa resposta. Você pode usá-lo em combinação com start-index para recuperar um subconjunto de elementos ou sozinho, para restringir o número de elementos retornados, começando pelo primeiro. Se max-results não for fornecido, a consulta retornará a quantidade máxima padrão de 1.000 linhas.
A Core Reporting API do Google Analytics retorna no máximo 10.000 linhas por solicitação, independentemente de quantas linhas você solicitar. Ela também pode retornar menos linhas do que o solicitado, quando não há a quantidade de segmentos de dimensão que você espera. Por exemplo, há menos de 300 valores possíveis para ga:country. Portanto, quando você segmenta somente por país, não é possível ver mais de 300 linhas, mesmo que defina max-results como um valor mais alto.

output

output=dataTable
Opcional.
Use esse parâmetro para definir o tipo de saída dos dados do Google Analytics retornados na resposta. Os valores permitidos são:
  • json: gera a propriedade rows padrão na resposta, com um objeto JSON.
  • dataTable: gera uma propriedade dataTable na resposta, com um objeto Data Table. É possível usar esse objeto Data Table diretamente com as visualizações de gráficos do Google.
Se não for fornecida, a resposta JSON padrão será usada.

fields

fields=rows,columnHeaders(name,dataType)
Opcional.

Especifica quais são os campos a serem retornados em uma resposta parcial. Se você usa somente um subconjunto dos campos na resposta da API, pode usar o parâmetro fields para especificar quais são os campos a serem incluídos.

O formato do valor do parâmetro de solicitação de campos se baseia vagamente na sintaxe XPath. A sintaxe compatível está resumida abaixo.

  • Use uma lista separada por vírgulas para selecionar vários campos.
  • Use a/b para selecionar um campo b que está aninhado dentro do campo a. Use a/b/c para selecionar um campo c aninhado dentro de b.
  • Use um subseletor para solicitar um conjunto de subcampos específicos de matrizes ou objetos colocando as expressões entre parênteses "( )".
    Por exemplo: fields=columnHeaders(name,dataType) retorna somente os campos name e dataType na matriz columnHeaders. Você também pode especificar um único subcampo, em que fields=columnHeader(name) é equivalente a fields=columnHeader/name.

prettyPrint

prettyPrint=false
Opcional.

Retorna a resposta em um formato legível se for true. Valor padrão: false.


quotaUser

quotaUser=4kh4r2h4
Opcional.

Permite que você aplique cotas por usuário de um aplicativo do servidor mesmo em casos nos quais o endereço IP do usuário é desconhecido. Isso pode ocorrer, por exemplo, com aplicativos que realizam tarefas cron no App Engine em nome de um usuário. Você pode escolher qualquer string arbitrária que identifique um usuário de maneira exclusiva, mas ela é limitada a 40 caracteres.

Ela substitui userIp, se ambos forem fornecidos.


Resposta

Se for bem-sucedida, essa solicitação retornará um corpo de resposta com a estrutura JSON definida abaixo. Se o parâmetro output estiver definido como dataTable, a solicitação retornará um corpo de resposta com a estrutura JSON (tabela de dados) definida abaixo.

Observação: o termo "resultados" refere-se ao conjunto inteiro de linhas que correspondem à consulta. Já "resposta" refere-se ao conjunto de linhas retornadas na página de resultados atual. Eles poderão ser diferentes, se o número total de resultados for maior que o tamanho da página da resposta atual, conforme explicado em itemsPerPage.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Campos de resposta

As propriedades da estrutura do corpo de resposta são definidas desta maneira:

Nome da propriedade Valor Descrição
kind string Tipo de recurso. O valor é "analytics#gaData".
id string Um ID para essa resposta de dados.
query object Esse objeto contém todos os valores transmitidos como parâmetros à consulta. O significado de cada campo é explicado na descrição do seu parâmetro de consulta correspondente.
query.start-date string Data de início.
query.end-date string Data de término.
query.ids string ID exclusivo da tabela.
query.dimensions[] list Lista de dimensões de análise.
query.metrics[] list Lista de métricas de análise.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Definido como "true" por padrão. Se definido como "false", as linhas em que todos os valores das métricas são zero serão omitidas da resposta.
query.sort[] list Lista de métricas ou dimensões nas quais os dados são classificados.
query.filters string Lista de filtros de métricas ou dimensões separados por vírgulas.
query.segment string Segmento do Google Analytics.
query.start-index integer Índice inicial.
query.max-results integer Número máximo de resultados por página.
startIndex integer Índice inicial de linhas especificado pelo parâmetro de consulta start-index. O valor padrão é 1.
itemsPerPage integer Número máximo de linhas que a resposta pode conter, independentemente do número real de linhas retornadas. Se o parâmetro de consulta max-results for especificado, o valor de itemsPerPage será o menor de max-results ou 10.000. O valor padrão de itemsPerPage é 1.000.
totalResults integer Número total de linhas no resultado da consulta, independentemente do número de linhas retornadas na resposta. Para consultas que resultam em um grande número de linhas, totalResults pode ser maior que itemsPerPage. Consulte Paginação para ver mais explicações sobre totalResults e itemsPerPage para grandes consultas.
startDate string Data de início da consulta de dados, conforme especificado pelo parâmetro start-date.
endDate string Data de término da consulta de dados, conforme especificado pelo parâmetro end-date.
profileInfo object Informações sobre a vista (perfil) para a qual os dados foram solicitados. Há dados da vista (perfil) disponíveis por meio da API de gerenciamento do Google Analytics.
profileInfo.profileId string Código da vista (perfil), como 1174.
profileInfo.accountId string ID da conta à qual essa vista (perfil) pertence, como 30481.
profileInfo.webPropertyId string ID da propriedade da Web à qual essa vista (perfil) pertence, como UA-30481-1.
profileInfo.internalWebPropertyId string ID interno da propriedade da Web à qual essa vista (perfil) pertence, como UA-30481-1.
profileInfo.profileName string Nome da vista (perfil).
profileInfo.tableId string Código da tabela da vista (perfil), que consiste em "ga:" seguido pelo código da vista (perfil).
containsSampledData boolean Verdadeiro se a resposta contém dados de amostra.
sampleSize string Número de amostras usadas para calcular os dados de amostra.
sampleSpace string Tamanho total do espaço de amostragem. Isso indica o tamanho total do espaço de amostra disponível do qual as amostras foram selecionadas.
columnHeaders[] list Cabeçalhos das colunas que indicam os nomes das dimensões seguidos pelos nomes das métricas. A ordem das dimensões e métricas é a mesma especificada na solicitação por meio dos parâmetros metrics e dimensions. O número de cabeçalhos é o número de dimensões + o número de métricas.
columnHeaders[].name string Nome da dimensão ou métrica.
columnHeaders[].columnType string Tipo de coluna. "DIMENSION" ou "METRIC".
columnHeaders[].dataType string Tipo de dados. Os cabeçalhos das colunas de dimensões usam somente STRING como tipo de dados. Os cabeçalhos das colunas de métricas têm tipos de dados para valores de métricas como INTEGER, PERCENT, TIME, CURRENCY, FLOAT etc. Consulte a resposta da API Metadata para ver todos os tipos possíveis.
totalsForAllResults object Valores totais das métricas solicitadas como pares de valores-chave de nomes e valores de métricas. A ordem dos totais de métricas é igual à ordem de métricas especificada na solicitação.
rows[] list Linhas de dados do Google Analytics, em que cada linha contém uma lista de valores das dimensões seguidos pelos valores das métricas. A ordem das dimensões e métricas é a mesma especificada na solicitação. Cada linha tem uma lista de campos N, em que N = número de dimensões + número de métricas.
JSON (tabela de dados)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Campos de resposta

As propriedades da estrutura do corpo de resposta são definidas desta maneira:

Nome da propriedade Valor Descrição
kind string Tipo de recurso. O valor é "analytics#gaData".
id string Um ID para essa resposta de dados.
query object Esse objeto contém todos os valores transmitidos como parâmetros à consulta. O significado de cada campo é explicado na descrição do seu parâmetro de consulta correspondente.
query.start-date string Data de início.
query.end-date string Data de término.
query.ids string ID exclusivo da tabela.
query.dimensions[] list Lista de dimensões de análise.
query.metrics[] list Lista de métricas de análise.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Definido como "true" por padrão. Se definido como "false", as linhas em que todos os valores das métricas são zero serão omitidas da resposta.
query.sort[] list Lista de métricas ou dimensões nas quais os dados são classificados.
query.filters string Lista de filtros de métricas ou dimensões separados por vírgulas.
query.segment string Segmento do Google Analytics.
query.start-index integer Índice inicial.
query.max-results integer Número máximo de resultados por página.
startIndex integer Índice inicial de linhas especificado pelo parâmetro de consulta start-index. O valor padrão é 1.
itemsPerPage integer Número máximo de linhas que a resposta pode conter, independentemente do número real de linhas retornadas. Se o parâmetro de consulta max-results for especificado, o valor de itemsPerPage será o menor de max-results ou 10.000. O valor padrão de itemsPerPage é 1.000.
totalResults integer Número total de linhas no resultado da consulta, independentemente do número de linhas retornadas na resposta. Para consultas que resultam em um grande número de linhas, totalResults pode ser maior que itemsPerPage. Consulte Paginação para ver mais explicações sobre totalResults e itemsPerPage para grandes consultas.
startDate string Data de início da consulta de dados, conforme especificado pelo parâmetro start-date.
endDate string Data de término da consulta de dados, conforme especificado pelo parâmetro end-date.
profileInfo object Informações sobre a vista (perfil) para a qual os dados foram solicitados. Há dados da vista (perfil) disponíveis por meio da API de gerenciamento do Google Analytics.
profileInfo.profileId string Código da vista (perfil), como 1174.
profileInfo.accountId string ID da conta à qual essa vista (perfil) pertence, como 30481.
profileInfo.webPropertyId string ID da propriedade da Web à qual essa vista (perfil) pertence, como UA-30481-1.
profileInfo.internalWebPropertyId string ID interno da propriedade da Web à qual essa vista (perfil) pertence, como UA-30481-1.
profileInfo.profileName string Nome da vista (perfil).
profileInfo.tableId string Código da tabela da vista (perfil), que consiste em "ga:" seguido pelo código da vista (perfil).
containsSampledData boolean Verdadeiro se a resposta contém dados de amostra.
sampleSize string Número de amostras usadas para calcular os dados de amostra.
sampleSpace string Tamanho total do espaço de amostragem. Isso indica o tamanho total do espaço de amostra disponível do qual as amostras foram selecionadas.
columnHeaders[] list Cabeçalhos das colunas que indicam os nomes das dimensões seguidos pelos nomes das métricas. A ordem das dimensões e métricas é a mesma especificada na solicitação por meio dos parâmetros metrics e dimensions. O número de cabeçalhos é o número de dimensões + o número de métricas.
columnHeaders[].name string Nome da dimensão ou métrica.
columnHeaders[].columnType string Tipo de coluna. "DIMENSION" ou "METRIC".
columnHeaders[].dataType string Tipo de dados. Os cabeçalhos das colunas de dimensões usam somente STRING como tipo de dados. Os cabeçalhos das colunas de métricas têm tipos de dados para valores de métricas como INTEGER, PERCENT, TIME, CURRENCY, FLOAT etc. Consulte a resposta da API Metadata para ver todos os tipos possíveis.
totalsForAllResults object Valores totais das métricas solicitadas como pares de valores-chave de nomes e valores de métricas. A ordem dos totais de métricas é igual à ordem de métricas especificada na solicitação.
dataTable object Um objeto Data Table que pode ser usado com gráficos do Google.
dataTable.cols[] list Uma lista de descritores de colunas para dimensões seguidos por métricas. A ordem das dimensões e métricas é a mesma especificada na solicitação por meio dos parâmetros metrics e dimensions. O número de colunas é o número de dimensões + o número de métricas.
dataTable.cols[].id string Um ID, que pode ser usado para se referir a uma coluna específica (como uma alternativa ao uso de índices de colunas). O ID da dimensão ou métrica é usado para definir esse valor.
dataTable.cols[].label string Um rótulo para a coluna (que pode ser exibido por uma visualização). O ID da dimensão ou métrica é usado para definir esse valor.
dataTable.cols[].type string O tipo de dados dessa coluna.
dataTable.rows[] list Linhas de dados do Google Analytics no formato de tabela de dados, em que cada linha é um objeto que contém uma lista de valores de células para dimensões seguidos por valores para métricas. A ordem das dimensões e métricas é a mesma especificada na solicitação. Cada célula tem uma lista de campos N, em que N = número de dimensões + número de métricas.

Códigos de erro

A Core Reporting API retornará um código de status HTTP 200, se uma solicitação for bem-sucedida. Se ocorrer um erro durante o processamento de uma consulta, a API retornará um código de erro e uma descrição. Cada aplicativo que usar a Google Analytics API precisará implementar a lógica correta de tratamento de erro. Para ver detalhes sobre os códigos de erro e saber como tratá-los, leia o Guia de referência de respostas de erro.

Faça um teste

Você pode fazer experiências com consultas à Core Reporting API.

  • Para ver as combinações válidas de métricas e dimensões em uma consulta, insira exemplos de valores para os parâmetros no Query Explorer. Os resultados do exemplo de consulta são apresentados como uma tabela com valores para todas as métricas e dimensões especificadas.

  • Para fazer uma solicitação de dados ativos e ver a resposta no formato JSON, faça uma experiência com o método analytics.data.ga.get no APIs Explorer de dados do Google.

Amostragem

O Google Analytics calcula determinadas combinações de dimensões e métricas de maneira imediata. Para retornar os dados em um período razoável, o Google Analytics pode processar somente uma amostra dos dados.

Para especificar o nível de amostragem a ser usado para uma solicitação, defina o parâmetro samplingLevel.

Se a resposta de uma Core Reporting API contiver dados de amostra, o campo de resposta containsSampledData será true. Além disso, duas propriedades fornecerão informações sobre o nível de amostragem da consulta: sampleSize e sampleSpace. Com esses dois valores, é possível calcular a porcentagem de sessões que foram usadas para a consulta. Por exemplo, se sampleSize é 201.000 e sampleSpace é 220.000, o relatório se baseia em (201.000 / 220.000) * 100 = 91,36% das sessões.

Consulte Amostragem para ver uma descrição geral da amostragem e saber como ela é usada no Google Analytics.


Gerenciamento de grandes resultados de dados

Se você espera que sua consulta retorne um grande conjunto de resultados, use as diretrizes a seguir para otimizar sua consulta de API, evitar erros e minimizar os excedentes de cota. Definimos uma linha de base de desempenho permitindo no máximo 7 dimensões e 10 métricas em qualquer solicitação de API. Embora o processamento de algumas consultas que especificam grandes quantidades de métricas e dimensões possa levar mais tempo que o de outras, limitar o número de métricas solicitadas pode não ser suficiente para melhorar o desempenho da consulta. Em vez disso, você pode usar as técnicas a seguir para conseguir os melhores resultados de desempenho.

Redução das dimensões por consulta

A API permite a especificação de até sete dimensões em qualquer solicitação. Muitas vezes, é necessário que o Google Analytics calcule os resultados dessas consultas complexas imediatamente. Isso poderá ser especialmente demorado se o número de linhas resultantes for alto. Por exemplo, consultar palavras-chave por cidade e por hora pode corresponder a milhões de linhas de dados. Você pode melhorar o desempenho reduzindo o número de linhas que o Google Analytics precisa processar. Para isso, limite o número de dimensões na sua consulta.

Divisão da consulta por período

Em vez de paginar pelos resultados principais por data de um período longo, avalie a possibilidade de formar consultas separadas para uma semana (ou até mesmo um dia) por vez. É claro que, para um grande conjunto de dados, até mesmo uma solicitação de dados de um único dia pode retornar mais que max-results. Nesse caso, não é possível evitar a paginação. Mas em todo caso, se o número de linhas correspondentes da consulta for maior que max-results, separar o período pode diminuir o tempo total para recuperar os resultados. Essa abordagem pode melhorar o desempenho em consultas de sequência única e paralelas.

Paginação

A paginação dos resultados pode ser uma maneira útil de dividir grandes conjuntos de resultados em blocos gerenciáveis. O campo totalResults informa o número existente de linhas correspondentes, e itemsPerPage informa o número máximo de linhas que podem ser retornadas no resultado. Se houver uma alta proporção de totalResults para itemsPerPage, é possível que as consultas individuais estejam levando mais tempo que o necessário. Se você precisa apenas de um número limitado de linhas, por exemplo, para fins de exibição, pode ser conveniente definir um limite explícito sobre o tamanho da resposta por meio do parâmetro max-results. No entanto, se seu aplicativo precisa processar um grande conjunto de resultados inteiro, solicitar o número máximo permitido de linhas pode ser mais eficiente.

Uso de gzip

Uma maneira fácil e conveniente de reduzir a largura de banda necessária para cada solicitação é ativar a compactação gzip. Embora isso exija tempo adicional de CPU para descompactar os resultados, a troca com os custos de rede geralmente é vantajosa. Para receber uma resposta codificada em gzip, você precisa realizar duas ações: definir um cabeçalho Accept-Encoding e modificar seu user-agent para conter a string gzip. Veja um exemplo de cabeçalhos HTTP corretos para ativar a compactação gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)