Reporting API de funis multicanal – guia de referência

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 ponto de extremidade 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 Reporting API de funis multicanal. Clique no nome de cada parâmetro para uma descrição detalhada.

Nome Valor Obrigatório Resumo
ids string sim O ID único da tabela no formato ga:XXXX, em que XXXX é o ID 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 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írgula 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:
  • 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.
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.

Detalhes dos parâmetros de consulta

ids

ids=ga:12345
Obrigatório.
O ID exclusivo usado para recuperar os dados dos funis multicanal. Esse ID é a concatenação do namespace 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 Management API do Google Analytics.

Voltar ao início

start-date

start-date=2011-10-01
Obrigatório.
Todas as solicitações de dados de funis multicanal devem obrigatoriamente especificar 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 start-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 sete dias (a partir de ontem) usando datas relativas:

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

Voltar ao início

end-date

end-date=2011-10-31
Obrigatório.
Todas as solicitações de dados de funis multicanal devem obrigatoriamente especificar 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

Voltar ao início

dimensions

dimensions=mcf:source,mcf:keyword
Opcional.

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.

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.

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)".

Voltar ao início

metrics

metrics=mcf:totalConversions,mcf:totalConversionValue
Obrigatório.

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 tem o parâmetro dimensions, as métricas retornadas fornecem valores agregados para o período solicitado, como valor total das conversões rejeições. 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 fonte.

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.

Voltar ao início

sort

sort=mcf:source,mcf:medium
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 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

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.

Voltar ao início

filters

filters=mcf: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 mcf:totalConversions e mcf:source da 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.

Voltar ao início

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.

Voltar ao início

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 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, quando você segmenta somente por mídia, não é possível ver mais de 300 linhas, mesmo que defina max-results como um valor mais alto.

Voltar ao início

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

JSON
{
  "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
    ]
  ],
}

Voltar ao início

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.
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 ID 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ões 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órios, onde cada linha contém uma lista de objetos Mcf.Rows. Essa lista interna representa os valores de dimensões seguidos pelos valores de métricas na mesma ordem especificada na solicitação. Cada linha tem uma lista de N campos, em que N = número de dimensões + número de métricas.

Um objeto Mcf.Rows envolve outro objeto que pode ser do tipo primitiveValue ou conversionPathValue. O tipo dos valores de dimensões pode ser qualquer um dos dois, mas todos os valores de métricas são do tipo primitiveValue.

Um primitiveValue é simplesmente uma string que envolve um objeto. Por exemplo:


{
  "primitiveValue": "2183"
}

Um conversionPathValue é um objeto que envolve uma variedade de objetos, em que cada um contém uma string nodeValue e uma string interactionType opcional. Por exemplo:


{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

Voltar ao início

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 ver detalhes sobre os códigos de erro e saber como tratá-los, leia o Guia de referência de respostas de erro.

Voltar ao início

Faça um teste

Você pode testar consultas na Reporting API de funis multicanal.

  • Para fazer uma solicitação de dados ativos e ver a resposta em formato JSON, tente usar o método analytics.data.mcf.get no Google APIs Explorer.

Voltar ao início

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 Reporting API de funis multicanal 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.

Voltar ao início

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)