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.
- Está criando um novo aplicativo? – Recomendamos que você use a versão 3.0 mais recente.
- Você usa a versão 2.3 legada? – Leia o Guia de migração para detalhes sobre como atualizar seu aplicativo para usar a nova versão.
Como começar
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 algumas etapas para ser registrado, autorizar o usuário e trabalhar com a API. Este tutorial guiará você em cada etapa e, ao final, você terá um aplicativo que pode ser personalizado.
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 conseguindo credenciais de autorização e passando-as 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.
captura de tela
- No Google Analytics, clique em Administrador na barra de menus. Selecione a conta e a propriedade às quais a Vista pertence. Na coluna VISTA DA PROPRIEDADE, clique em Configurações da vista da propriedade para obter o ID da vista.
captura de tela
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 interativo para explorar todas as dimensões e métricas expostas pela API. Leia também 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.