Este documento fornece a referência completa para consulta e resposta da Reporting API de funis multicanal.
Introdução
A Reporting API de funis multicanal permite solicitar os dados do Relatório de funis multicanal do Google Analytics de um usuário autenticado. Cada relatório é composto por estatísticas derivadas dos dados que o código de acompanhamento envia de volta ao Google Analytics, organizadas como dimensões e métricas. Ao escolher suas próprias combinações de dimensões e métricas, você pode usar a Reporting API para criar relatórios personalizados adaptados às suas próprias especificações.
A API contém um único método que solicita os dados do relatório: report.get. Com esse método, você fornece o ID da tabela que corresponde à vista (perfil) da qual deseja recuperar dados. Além disso, você especifica o seguinte:
- Uma combinação de dimensões e métricas.
- Um período.
- Um conjunto de parâmetros de opção que controlam quais dados são retornados
A API disponibiliza o método report.get em um endpoint REST: https://www.googleapis.com/analytics/v3/data/mcf. A seção a seguir mostra um exemplo de solicitação e descreve cada um dos parâmetros.
Solicitação
A API fornece um único método para solicitar dados:
analytics.data.mcf.get()
Também é possível consultar a API como um ponto de extremidade REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Cada parâmetro de consulta de URL especifica um parâmetro de consulta de API que deve obrigatoriamente ser codificado por URL.
Todas as solicitações feitas à Reporting API de funis multicanal devem ser obrigatoriamente autorizadas, preferencialmente por meio do OAuth 2.0.
Resumo dos parâmetros de consulta
A tabela a seguir resume todos os parâmetros de consulta aceitos pela API de relatórios de funis multicanal. 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 mcf:totalConversions,mcf:totalConversionValue.
Uma consulta válida precisa especificar pelo menos uma métrica. |
dimensions |
string |
não | Uma lista de dimensões separadas por vírgulas para seu Relatório de funis multicanal, como mcf:source,mcf:keyword. |
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. |
samplingLevel |
string |
não | O nível de amostragem desejado. Valores permitidos:
|
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. |
Detalhes dos parâmetros de consulta
ids
ids=ga:12345
ga: com o ID da vista (perfil) do relatório. Você pode recuperar o ID da vista (perfil) do seu relatório usando o método analytics.management.profiles.list, que fornece o id no recurso de vista (perfil) na
API Management do Google Analytics.
start-date
start-date=2011-10-01
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 é 2011-01-01.
Não há restrições de limite superior para uma start-date.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=2011-10-31
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=mcf:source,mcf:keyword
O parâmetro de dimensões define as chaves de dados principais para seu Relatório de funis multicanal, como mcf:source ou mcf:medium.
Use dimensões para segmentar suas métricas de conversão. Por exemplo, embora você possa solicitar o número total de conversões do seu site, pode ser mais interessante solicitar o número de conversões segmentadas por mídia.
Nesse caso, você veria o número de conversões provenientes de pesquisas orgânicas, referências, e-mails 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.
Valores não disponíveis
Quando o valor da dimensão não pode ser determinado, o Google Analytics utiliza a string especial "(not set)".
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
As estatísticas agregadas da atividade do usuário no seu site, como contagem total de conversões ou valor total das conversões.
Se uma consulta não tiver um parâmetro dimensions, as métricas retornadas vão fornecer valores agregados para o período solicitado, como o valor total de conversão. No entanto, quando são solicitadas dimensões, os valores são segmentados por valor da dimensão.
Por exemplo, mcf:totalConversions solicitado com mcf:source retorna o total de conversões por origem.
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.
sort
sort=mcf:source,mcf:medium
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 responder à pergunta "Quais são minhas principais origens de conversão e por meio de quais mídias?",
você pode fazer uma consulta com o parâmetro a seguir. Ele classifica primeiro por mcf:source e depois por mcf:medium, ambos em ordem crescente:
sort=mcf:source,mcf:medium
Para responder à pergunta relacionada "Quais são minhas principais mídias de conversão e as origens delas?", você pode fazer uma consulta com o parâmetro a seguir. Ele classifica primeiro por mcf:medium e depois por mcf:source, ambos em ordem crescente:
sort=mcf:medium,mcf:source
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
dimensionsoumetrics. 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=mcf: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 mcf:totalConversions e mcf:source para a vista (perfil) 12134, em que a dimensão mcf:medium é a string referral:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Consulte a Referência da Core Reporting API para ver detalhes.
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.max-results
max-results=100
Número máximo de linhas a serem incluídas nessa resposta. É possível 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á o máximo padrão de 1.000 linhas.
A Reporting API de funis multicanal 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 mcf:medium. Portanto, ao segmentar somente por mídia, não é possível exibir mais de 300 linhas, mesmo que você defina max-results como um valor mais alto.
Resposta
Se for bem-sucedida, essa solicitação retornará um corpo de resposta com a estrutura JSON 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.
Formato da resposta
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
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#mcfData". |
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.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.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Índice inicial de linhas. O valor padrão é 1. |
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.
|
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 Management API 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 |
ID da tabela da vista (perfil), que consiste em "ga:" seguido pelo ID 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ão têm apenas "STRING" ou "MCF_SEQUENCE" como tipo de dados.
Os cabeçalhos das colunas de métricas têm tipos de dados para valores de métricas como "INTEGER", "DOUBLE", "CURRENCY" etc. |
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 de relatório, em que cada linha contém uma lista de objetos Um objeto Um
{
"primitiveValue": "2183"
}
Um
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Códigos de erro
A Reporting API de funis multicanal 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.
Confira!
Use o APIs Explorer abaixo para chamar esse método em dados ativos e ver a resposta.
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 MCF 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)