O que é a API de relatórios principais – visão geral

Este documento fornece uma visão geral de nível superior da API de relatórios principais versão 3.0 do Google Analytics. Para referências detalhadas sobre a API, consulte o Guia de referência.

Introdução

A API de relatórios principais do Google Analytics concede a você acesso à maior parte dos dados de relatório do Google Analytics. Com ela, você pode:

  • criar painéis personalizados para exibir os dados do Google Analytics;
  • economizar tempo ao automatizar tarefas de relatório complexas;
  • integrar seus dados do Google Analytics a outros aplicativos de negócios.

Escolha de uma versão

Recentemente, nós lançamos uma nova versão da API de relatórios principais.

  • Você está criando um novo aplicativo? Recomendamos que utilize a versão 3.0 mais recente.
  • Está usando a versão 2.3 legada? Leia o Guia de migração para detalhes sobre como atualizar seu aplicativo para utilizar a nova versão.

Primeiros passos

Quer dar os primeiros passos imediatamente? Leia o Tutorial de apresentação da Google Analytics API.

Cada aplicativo que usa a API precisa passar por duas etapas para se registrar, autorizar o usuário e trabalhar com a API. Esse tutorial orienta você ao longo de cada etapa e, no final, você terá um aplicativo personalizável em funcionamento.

Visão geral conceitual

A API de relatórios principais retorna dados de relatório que consistem em estatísticas derivadas dos dados coletados pelo código de acompanhamento do Google Analytics. Cada relatório é organizado como dimensões e métricas. Você usa API de relatórios principais para consultar dimensões e métricas com o objetivo de criar relatórios personalizados.

Existem três conceitos fundamentais subjacentes à API de relatórios principais:

  1. Como os relatórios estão relacionados aos usuários e às vistas da propriedade (perfis).
  2. A estrutura de um relatório e como criar consultas.
  3. Trabalho com a resposta da API.

Relatórios, usuários e vistas da propriedade (perfis)

Para solicitar os dados de relatório de um usuário, seu aplicativo precisa identificar o usuário e especificar uma vista da propriedade (perfil) para a qual recuperar os dados. Um usuário é identificado pela obtenção das credenciais de autorização e envio dessas credenciais em cada solicitação de API. Uma vista da propriedade (perfil) faz parte da hierarquia de configuração do Google Analytics e é identificada por um ID de vista da propriedade (perfil).

Existem algumas maneiras de encontrar o ID da sua vista da propriedade (perfil).

  • Seu aplicativo pode usar a API de gerenciamento para percorrer a hierarquia de configuração de gerenciamento e obter um ID de vista da propriedade (perfil).
  • No URL de cada relatório no Google Analytics.
  • No Google Analytics, clique em Administrador na barra do menu. Selecione a conta e a propriedade às quais a Vista pertence. Na coluna VISTA, clique em Configurações da Vista para descobrir o ID da Vista.

Consulta de dimensões e métricas

Você consulta a API para encontrar dados de relatório do Google Analytics, que consistem em dimensões e métricas. As métricas são avaliações individuais das atividades dos usuários na sua propriedade, como sessões e exibições de página. As dimensões dividem as métricas de acordo com alguns critérios comuns, como país ou navegador. Ao criar uma consulta, você especifica quais dimensões e métricas deseja ver nos dados do seu relatório.

Use o Guia de referência de dimensões e métricas para explorar todas as dimensões e métricas expostas pela API. Além disso, leia o Guia de referência da API de relatórios principais para saber como especificar dimensões e métricas em uma consulta de API.

Trabalho com relatórios

Os dados retornados da API podem ser considerados como uma tabela com um cabeçalho e diversas linhas. Cada resposta de API consiste em um cabeçalho que descreve o nome e o tipo dos dados de cada coluna. A resposta também inclui uma lista de linhas, em que cada linha é uma lista de células com dados na mesma ordem que os cabeçalhos. Você usa as informações no cabeçalho para determinar o tipo de dados de cada célula.

Leia o Guia de referência da API de relatórios principais para mais informações sobre a resposta da API.

Voltar ao início

Políticas de cotas e de suspensão de uso

A Google Analytics API processa milhões de operações. Para impedir que o sistema receba mais operações do que pode processar e para garantir uma distribuição equitativa dos respectivos recursos, é necessário empregar um sistema de cotas. Consulte o guia Limites e cotas para ver os limites específicos.

Para detalhes sobre como são tratadas as alterações às colunas da API de relatórios principais (ou seja, dimensões e métricas), consulte a Política de suspensão de uso de dados. Para saber como a API de metadados pode ser usada para verificar a existência de colunas com uso suspenso, consulte o Guia do desenvolvedor da API de metadados.

Próximas etapas

Agora que você entende como a API funciona, existem vários recursos para ajudar a dar os primeiros passos:

  • Leia o Guia do desenvolvedor para aprender a trabalhar com a API.
  • Use a ferramenta interativa Query Explorer para criar consultas visualmente e ver a resposta por meio da API.
  • Leia o artigo Consultas comuns, que lista várias das consultas mais frequentes da API de relatórios principais.
  • Consulte a referência de Dimensões e métricas para ver uma lista de todos os dados disponíveis por meio da API.
  • Consulte a página Bibliotecas e amostras para ver uma lista com todas as bibliotecas cliente disponíveis que podem ser usadas com essa API.

Voltar ao início