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:
- Como os relatórios estão relacionados aos usuários e às vistas da propriedade (perfis).
- A estrutura de um relatório e como criar consultas.
- 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.
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.