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 API de relatórios principais. Clique no nome de cada parâmetro para conferir 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 formatada como 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
formatada como 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:
|
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
junto 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. false padrão.
|
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. Exemplo:
key=AldefliuhSFADSfasdfasdfASdf . |
Detalhes dos parâmetros de consulta
ids
ids=ga:12345
ga:
com o ID da vista (perfil) do Google Analytics. Você pode recuperar o ID da vista (perfil) usando o método analytics.management.profiles.list
, que fornece o id
no recurso de vista da propriedade (perfil) na API Management do Google Analytics.
start-date
start-date=2009-04-20
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 today
, yesterday
ou o padrão NdaysAgo
.
Os valores precisam corresponder a
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
start-date
válido é 2005-01-01
.
Não há restrições de limite superior para uma data de início.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
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 today
, yesterday
ou o padrão NdaysAgo
.
Os valores precisam corresponder a
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
end-date
válido é
2005-01-01
. Não há restrição de limite superior para uma end-date
. 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
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.
Ao usar dimensions
em uma solicitação de dados, esteja ciente 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
dimensions
, as métricas retornadas vão fornecer valores agregados para o período solicitado, como visualizações gerais de página ou 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
solicitado com ga:country
retorna o total de visualizações de página por país.
Ao solicitar métricas, lembre-se do seguinte:
- 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
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.
- A direction de classificação é definida por padrão como crescente e pode ser alterada para decrescente usando um prefixo de sinal de menos (
-
) 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 à pergunta relacionada "Quais são meus principais navegadores e quais países mais os usam?", 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
Ao usar o parâmetro sort
, lembre-se do seguinte:
- Classifique somente por valores de dimensões ou métricas que você usou nos parâmetros
dimensions
oumetrics
. 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
O parâmetro de string de consulta filters
restringe os dados retornados da sua solicitação. Para usar o parâmetro filters
, forneça uma dimensão ou métrica para filtrar, 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 ocorre antes de qualquer dimensão ser 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 ocorre 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 filtro único uso 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
filtra a métrica de visualizações de página. - 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, já que o Query Explorer codifica automaticamente URLs que contêm strings e espaços.
Operador | Descrição | Formulário codificado pelo URL | Exemplos |
---|---|---|---|
== |
Igual a | %3D%3D |
Retorna resultados em que o tempo na página é exatamente 10 segundos:filters=ga:timeOnPage%3D%3D10 |
!= |
Diferente de | !%3D |
Retorna resultados em que o tempo na página não é de 10 segundos:filters=ga:timeOnPage!%3D10 |
> |
Maior que | %3E |
Retorna resultados em que o tempo na página é estritamente maior que 10 segundos:filters=ga:timeOnPage%3E10 |
< |
Menor que | %3C |
Retorna resultados em que o tempo na página é estritamente menor que 10 segundos:filters=ga:timeOnPage%3C10 |
>= |
Maior ou igual a | %3E%3D |
Retorna resultados em que o tempo na página é de dez segundos ou mais:filters=ga:timeOnPage%3E%3D10 |
<= |
Menor ou igual a | %3C%3D |
Retorna resultados em que o tempo na página é de até 10 segundos:filters=ga:timeOnPage%3C%3D10 |
Operador | Descrição | Formulário codificado pelo URL | Exemplo |
---|---|---|---|
== |
Correspondência exata | %3D%3D |
Métricas agregadas em que a cidade é Irvine:filters=ga:city%3D%3DIrvine |
!= |
Sem correspondência | !%3D |
Métricas agregadas em que a cidade não é Irvine:filters=ga:city!%3DIrvine |
=@ |
Contém substring | %3D@ |
Métricas agregadas em que 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 em que a cidade começa com Nova:filters=ga:city%3D~%5ENew.* (%5E é o URL codificado do caractere ^ que ancora um padrão ao início da string.) |
!~ |
Não corresponde à expressão regular | !~ |
Métricas agregadas em que a cidade não começa com Nova: filters=ga:city!~%5ENew.* |
Expressões de filtro
Existem algumas regras importantes para expressões de filtro:
- Caracteres reservados pelo URL: caracteres como
&
precisam ser 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
\,
- ponto e 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 têm estas regras adicionais:- Comprimento 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.
- Comprimento máximo de 128 caracteres: expressões regulares maiores que 128 caracteres resultam em um código de status
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 o uso de 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 OU 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
E
O operador AND
é definido com um 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 E o navegador é Firefox:
ga:country==United%20States;ga:browser==Firefox
O país é Estados Unidos E o idioma não começa com "en":
ga:country==United%20States;ga:language!~^en.*
O sistema operacional é (Windows OR Macintosh) E o navegador é (Firefox OR Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
O país é Estados Unidos E as sessões são maiores que 5:
ga:country==United%20States;ga:sessions>5
segmentar
segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
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 em 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
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.
DEFAULT
será
usado.include-empty-rows
include-empty-rows=true
start-index
start-index=10
1
. Os índices de resultados baseiam-se em 1. Ou seja, a primeira linha é a linha 1
, não a linha 0
. Use esse parâmetro como um mecanismo de paginação com o parâmetro max-results
para situações em que totalResults
excede 10.000 e você quer recuperar linhas indexadas a partir de 10.001.max-results
max-results=100
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á o máximo padrão de 1.000 linhas.ga:country
. Portanto, ao segmentar somente por país, não é possível exibir mais de 300 linhas, mesmo que você defina max-results
como um valor mais alto.saída
output=dataTable
json
: gera a propriedaderows
padrão na resposta, contendo um objeto JSON.dataTable
: gera uma propriedadedataTable
na resposta, contendo um objeto de tabela de dados. Esse objetoData Table
pode ser usado diretamente com as visualizações de gráficos do Google.
campos
fields=rows,columnHeaders(name,dataType)
Especifica quais são os campos a serem retornados em uma resposta parcial. Se você usa apenas um subconjunto dos campos na resposta da API, pode usar o parâmetro fields
para especificar quais campos incluir.
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 diversos campos.
- Use
a/b
para selecionar um campo b aninhado dentro do campo a. Usea/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. Basta colocar expressões entre parênteses
"( )"
.
Por exemplo:fields=columnHeaders(name,dataType)
retorna somente os camposname
edataType
na matrizcolumnHeaders
. Também é possível especificar um único subcampo, em quefields=columnHeader(name)
é equivalente afields=columnHeader/name
.
prettyPrint
prettyPrint=false
Retorna a resposta em um formato legível se true
.
Valor padrão: false
quotaUser
quotaUser=4kh4r2h4
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.
Isso vai substituir 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.
{
"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 . |
selfLink |
string |
Link para essa página de resultados dessa consulta de dados. |
previousLink |
string |
Link para a página anterior de resultados dessa consulta de dados. |
nextLink |
string |
Link para a próxima página de resultados dessa consulta de dados. |
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 de metadados para ver todos os tipos de dados 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 N campos, em que N = o número de dimensões + o número de métricas. |
{
"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 . |
selfLink |
string |
Link para essa página de resultados dessa consulta de dados. |
previousLink |
string |
Link para a página anterior de resultados dessa consulta de dados. |
nextLink |
string |
Link para a próxima página de resultados dessa consulta de dados. |
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 de metadados para ver todos os tipos de dados 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 = o número de dimensões + o 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 mais detalhes sobre os códigos de erro e como lidar com eles, 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, tente 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 uma resposta da API Core Reporting 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
for 201,000
e sampleSpace
for 220,000
,o relatório vai se basear
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 um valor de referência de desempenho permitindo no máximo 7 dimensões e 10 métricas em uma solicitação de API. Algumas consultas que especificam um grande número de métricas e dimensões podem levar mais tempo para serem processadas do que outras, mas 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 especificar até sete dimensões em qualquer solicitação. Muitas vezes, o Google Analytics precisa calcular 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, mesmo uma
solicitação de dados de um único dia pode retornar mais de
max-results
. Nesse caso, não é possível evitar a paginação. Mas, em qualquer caso, se o número de linhas correspondentes para sua 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 quantas linhas correspondentes existem, e itemsPerPage
fornece o número máximo de linhas que podem ser retornadas no resultado.
Se houver uma alta proporção de totalResults
para itemsPerPage
, as consultas individuais podem estar demorando mais do que o necessário. Se você precisa 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, é preciso 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)