Neste documento, mostramos como migrar o código existente da API Google Analytics Reporting v4 para a API Google Analytics Data v1 e apresentamos uma visão geral das principais diferenças entre as duas APIs.
Por que preciso migrar?
Se seu aplicativo precisar acessar dados em uma propriedade do Google Analytics 4, será necessário atualizar o código para usar a API Data v1, já que a API Reporting v4 só pode acessar propriedades criadas com o Universal Analytics.
Pré-requisitos
Veja os princípios básicos da API Data v1 no guia de início rápido.
Como começar
Para começar, crie uma propriedade do Google Analytics 4, ative a API Data v1 e configure uma biblioteca de cliente da API adequada para sua plataforma.
Criar uma propriedade do Google Analytics 4
Antes de iniciar a migração do seu código para que seja compatível com a API Data v1, é necessário migrar seu site para usar uma propriedade do Google Analytics 4. Não é possível preencher uma propriedade do Google Analytics 4 com dados históricos de uma propriedade do Universal Analytics.
Ativar a API
Clique nesse botão para ativar automaticamente a API Data v1 no projeto do Google Cloud selecionado.
Ativar a API Google Analytics Data v1Usar uma biblioteca de cliente
Instalar uma biblioteca de cliente
Se você usar uma biblioteca de cliente, precisará instalar a biblioteca da API Data v1 para sua linguagem de programação.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Inicializar uma biblioteca de cliente
As bibliotecas de cliente da API Data v1 ajudam você a começar rapidamente. Por padrão, elas tentam encontrar de forma automática as credenciais da sua conta de serviço.
Uma maneira fácil de recuperar as credenciais é definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. O cliente da API usará o valor dessa variável para encontrar o arquivo JSON da chave da conta de serviço.
Por exemplo, é possível definir essas credenciais executando o comando abaixo e usando o caminho para o arquivo JSON da conta de serviço:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Veja a seguir os snippets de código normalmente usados para inicializar as bibliotecas de cliente da API Data v1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Em vez de usar uma variável de ambiente, também é possível enviar as informações de credenciais para uma instância do cliente da API de forma explícita durante a inicialização. Veja abaixo os snippets usados para inicializar as bibliotecas de cliente da API Data v1 transmitindo credenciais explicitamente no código.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Sem usar uma biblioteca de cliente
Se você utilizava a API Reporting v4 sem uma biblioteca de cliente e quer continuar essa prática com a API Data v1, ainda poderá usar suas credenciais.
É preciso usar o novo endpoint HTTP e o documento de descoberta que acompanham a API Data:
Se o código usa um documento de descoberta, é necessário atualizá-lo para referenciar o documento da API Data v1:
Depois de atualizar o endpoint, familiarize-se com a nova estrutura de solicitação e os conceitos da API Data para atualizar sua consulta JSON.
Principais relatórios
Métodos de geração de relatórios disponíveis
A API Reporting v4 oferece um único método batchGet para acessar os recursos de geração de relatórios central. A API Data v1 oferece vários métodos de geração de relatórios central:
- runReport: retorna um relatório personalizado dos seus dados de eventos do Google Analytics. Ele não é compatível com o recurso de tabela dinâmica e é o método preferido para consultas simples de relatórios.
- runPivotReport: retorna um relatório dinâmico personalizado com os dados de eventos do Google Analytics. Assim como nas tabelas dinâmicas da API Reporting v4, cada uma delas descreve as colunas e linhas de dimensões visíveis na resposta do relatório.
- batchRunReports: é uma versão em lote do método
runReportque permite gerar vários relatórios usando uma única chamada de API. - batchRunPivotReports: é uma versão em lote do método
runPivotReportque permite gerar vários relatórios usando uma única chamada de API.
O propósito de ter vários métodos de geração de relatórios é a praticidade, porque alguns métodos aceitam recursos mais complexos que outros (tabelas dinâmicas, agrupamento em lote), mas compartilham uma estrutura de solicitação semelhante.
Mudanças no esquema da API
Os recursos de geração de relatórios da API Reporting e da API Data são determinados principalmente pelo esquema, ou seja, dimensões e métricas compatíveis com consultas. Há diferenças significativas nos esquemas das APIs devido às diferenças conceituais entre o Universal Analytics e o Google Analytics 4.
- Confira a lista atualizada de dimensões e métricas compatíveis com a API Data. No momento, todas as dimensões e métricas são compatíveis entre si. Portanto, não é necessário usar o Explorador de dimensões e métricas para determinar as combinações aceitas. Esse comportamento mudará no futuro.
- É possível conferir as dimensões personalizadas no Google Analytics 4 usando a sintaxe das dimensões personalizadas da API Data v1, que devem ser utilizadas no lugar dos slots de dimensão ga:dimensionXX da API Reporting v4.
- É possível conferir as dimensões personalizadas no Google Analytics 4 usando a sintaxe das dimensões personalizadas da API Data v1, que devem ser utilizadas no lugar dos slots de métrica ga:metricXX da API Reporting v4.
- Algumas dimensões e métricas do Universal Analytics têm um equivalente direto no Google Analytics 4. Consulte o gráfico de equivalência de esquemas da API UA/GA4 para mais informações.
- Os nomes de dimensões e métricas não têm mais o prefixo
ga:no Google Analytics 4. - Alguns recursos do Universal Analytics ainda não estão disponíveis no GA4 (por exemplo, integração com o Campaign Manager, DV360 e Search Ads 360). Quando eles forem implementados no Google Analytics 4, poderão ser usados na API Data. Novas dimensões e métricas serão adicionadas ao esquema da API.
Entidades
O Google Analytics 4 não tem o conceito de vistas (perfis) do Universal Analytics. Como resultado, não há o parâmetro viewId nas solicitações de relatórios da API Data v1. Em vez disso, é necessário especificar um ID numérico de propriedade do Google Analytics 4 em um caminho de URL de solicitação ao chamar os métodos da API Data v1.
Esse comportamento é diferente da API Reporting v4, que se baseia nos IDs da vista (perfil) para identificar a entidade de geração de relatório.
API Data v1
No caso da API Data v1, um ID numérico da propriedade do Google Analytics 4 precisa ser especificado no caminho do URL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
API Reporting v4
A API Reporting v4 requer que um ID da vista (perfil) do Universal Analytics seja especificado no corpo de uma consulta de relatório.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Se você estiver usando uma das bibliotecas de cliente da API Data, não será necessário manipular manualmente o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property que deve ser preenchido com uma string no formato properties/GA4_PROPERTY_ID. Consulte o guia de início rápido para exemplos de como usar as bibliotecas de cliente.
Períodos
Tanto a API Reporting v4 quanto a API Data v1 são compatíveis com vários períodos especificados usando o campo dateRanges em uma solicitação de geração de relatório. Ambas as APIs utilizam o mesmo formato de entrada de data e aceitam valores absolutos de data no formato YYYY-MM-DD ou datas relativas como yesderday, today, 7daysAgo etc.
As solicitações da API Data v1 estão limitadas a quatro períodos, enquanto a API Reporting v4 permite dois em uma única solicitação de relatório.
Cada dateRange na API Data v1 pode ter um campo name opcional que pode ser usado para referenciar o período correspondente em uma resposta.
Se name não for indicado, o nome do período será gerado automaticamente.
Quando vários períodos são especificados em uma solicitação da API Data v1, uma nova dimensão dateRange é adicionada de forma automática a uma resposta, e o nome do período é usado como um valor de dimensão. Esse comportamento é diferente da API Reporting v4, que retorna dados para um período como um grupo de valores de métricas em cada linha.
Solicitação da API Data v1
Um campo name opcional é usado para cada valor de dateRange em uma solicitação.
Esse nome será usado como um valor da dimensão dateRange na resposta.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Resposta da API Data v1
Outra dimensão dateRange é incluída automaticamente na resposta.
O valor da dimensão dateRange contém o nome de um período que é proveniente do campo dateRange.name ou é gerado automaticamente.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Solicitação da API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Resposta da API Reporting v4
Na API Reporting v4, os valores de cada período são agrupados no campo metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Classificação
O comportamento de pedido das consultas de relatório da API Data v1 pode ser controlado com o campo orderBys, que é semelhante ao campo orderBys da API Reporting v4.
A especificação OrderBy foi alterada na API Data v1.
Cada OrderBy pode conter uma das seguintes opções:
- DimensionOrderBy, classifica os resultados pelos valores de uma dimensão.
- MetricOrderBy, classifica os resultados pelos valores de uma métrica.
- PivotOrderBy, usado em consultas dinâmicas e classifica os resultados pelos valores de uma métrica em um grupo de colunas dinâmicas.
Os tipos de pedido DELTA, SMART, HISTOGRAM_BUCKET compatíveis com a API Reporting v4 não são implementados na API Data v1.
O tipo de pedido OrderType.NUMERIC da API Data v1 é equivalente ao valor OrderType.DIMENSION_AS_INTEGER da API Reporting v4.
Solicitação da API Data v1
Este exemplo mostra uma consulta que informa a contagem de sessões por país, organizando as linhas pela métrica sessions em ordem decrescente.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Resposta da API Data v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Solicitação da API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Resposta da API Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Filtragem
As cláusulas dimensionFilter e metricFilter da API Data v1 podem ser usadas para solicitar que a API retorne dados apenas para valores específicos de dimensões ou métricas. Elas são semelhantes às cláusulas dimensionFilterClauses e metricFilterClauses da API Reporting v4.
A API Data v1 não é compatível com strings de expressão de filtro, como a cláusula filtersExpression da API Reporting v4. Essas expressões precisam ser gravadas novamente usando as cláusulas dimensionFilter e metricFilter.
Solicitação da API Data v1
Este exemplo de solicitação retorna uma lista de contagens de sessão para determinados caminhos de página visitados pelos usuários.
A cláusula dimensionFilter é usada para retornar apenas as linhas com os valores de dimensão pagePath, começando com /webstore/ e contendo a string action=a12345.
A cláusula metricFilter solicita que o método runReport retorne apenas as linhas com os valores de métrica sessions maiores que 1.000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Solicitação da API Reporting v4
Este exemplo de solicitação é semelhante ao exemplo da API Data v1. Ele retorna uma lista de contagens de sessões de determinados caminhos de página visitados pelos usuários.
O campo dimensionFilterClauses é usado para retornar somente as linhas com os valores de dimensão pagePath começando com /webstore/ e contendo a string action=a12345.
O campo metricFilterClauses é usado para retornar somente as linhas com os valores de métrica ga:sessions maiores que 1.000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Paginação
A API Data v1 usa os campos limit e offset para a paginação com resultados de resposta que abrangem várias páginas, enquanto a API Reporting v4 utiliza pageToken e pageSize.
Para solicitações de tabela dinâmica da API Data v1, use os campos limit e offset do objeto Pivot para implementar a paginação individualmente. O campo limit agora é obrigatório para cada objeto Pivot.
Por padrão, a API Data v1 retorna no máximo as primeiras 10 mil linhas de dados de evento, em que o valor padrão para a API Reporting v4 é de 1.000 linhas.
O número total de linhas que correspondem à consulta é retornado usando o campo rowCount em uma resposta da API Data v1, semelhante à API Reporting v4.
Solicitação da API Data v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Resposta da API Data v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Solicitação da API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Resposta da API Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Agregações de métricas
A API Data v1 calcula os valores de agregação apenas quando o campo metricAggregations é especificado em uma solicitação. Por outro lado, a API Reporting v4 retorna os valores total, mínimo e máximo de cada métrica por padrão, a menos que os campos hideTotals ehideValueRanges sejam definidos como true.
Solicitação da API Data v1
As agregações só serão calculadas se o campo metricAggregations for especificado em uma solicitação.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Resposta da API Data v1
As linhas de métricas agregadas são retornadas nos campos totals, minimum e maximum de uma resposta. Para essas linhas, o campo dimensionValues contém um valor especial de RESERVED_TOTAL, RESERVED_MAX ou RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Solicitação da API Reporting v4
Um exemplo de solicitação para retornar a contagem de sessões por país.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Resposta da API Reporting v4
Os campos totals, minimums e maximums estão presentes por padrão em uma resposta da API Reporting v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Tabelas dinâmicas
A API Data v1 é compatível com o recurso de tabela dinâmica nos métodos de geração de relatórios runPivotReport e batchRunPivotReports.
A API Reporting v4 permite incluir pivots em consultas de relatórios usando o método batchGet.
As tabelas dinâmicas são implementadas de forma diferente na API Data v1 em comparação com a API Reporting v4. Na primeira, cada linha de resposta representa uma única célula da tabela e, na API Reporting v4, uma única linha de resposta representa uma linha de tabela completa.
API Data v1
Veja abaixo um fragmento de uma resposta da API Data v1 para a consulta runPivotReport. Cada célula do relatório dinâmico é retornada individualmente:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
API Reporting v4
Veja abaixo um fragmento de uma resposta da API Reporting v4 para a consulta batchGet. Uma única linha de resposta representa uma linha de tabela completa com todos os valores de métricas para a tabela dinâmica em pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Na API Data v1, cada dimensão da consulta runPivotReport ou batchRunPivotReports precisa ser definida em um objeto dinâmico. A dimensão só será visível em um relatório se for usada em pelo menos uma tabela dinâmica de uma consulta dinâmica.
As colunas dinâmicas da API Data v1 são especificadas usando o campo fieldNames em vez do campo dimensions da API Reporting v4.
Utilize um filtro de dimensão no escopo da solicitação se quiser filtrar dimensões em uma solicitação de geração de relatórios da API Data v1. Esse processo é diferente da API Reporting v4, em que é possível especificar dimensionFilterClauses em um objeto dinâmico.
O campo offset da API Data v1 é funcionalmente semelhante ao campo startGroup da API Reporting v4.
O campo limit da API Data v1 é semelhante ao maxGroupCount da API Reporting v4 e deve ser usado para limitar a cardinalidade do relatório.
A API Data v1 é compatível com várias tabelas dinâmicas, desde que o produto do parâmetro limit para cada tabela não exceda 100.000. A API Reporting v4 aceita apenas uma dimensão de tabela dinâmica.
Por padrão, a API Data v1 classifica as dimensões em uma tabela dinâmica pela primeira métrica no relatório. Esse comportamento é diferente da API Reporting v4, em que a ordem é determinada pela ordem decrescente do total das métricas solicitadas. Para especificar a ordem de classificação na API Data v1, use o campo orderBys de uma especificação de tabela dinâmica.
Solicitação da API Data v1
A seguinte consulta dinâmica da API Data v1 cria um relatório de contagens de sessões por país, dinamizado pela dimensão browser. Observe como a consulta usa os campos orderBys, limit e offset para reproduzir o comportamento de uma consulta da API Reporting v4 para preservar as configurações de classificação e paginação.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Resposta da API Data v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Solicitação da API Reporting v4
A seguinte consulta de tabela dinâmica da API Reporting v4 cria um relatório de contagens de sessões por país, dinamizado pela dimensão ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Resposta da API Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Coortes
A API Data v1 usa a especificação CohortSpec para configurar os relatórios de coorte. Ela é semelhante à especificação CohortGroup da API Reporting v4.
No momento, todas as métricas disponíveis na API Data v1 são compatíveis com consultas de coorte. No entanto, para a API Reporting v4, apenas um subconjunto de métricas especiais pode ser usado em uma consulta de coorte.
Em uma solicitação de coorte da API Data v1, a métrica cohortActiveUsers é obrigatória.
Tanto a API Data v1 quanto a API Reporting v4 permitem até 12 coortes em uma única solicitação.
No momento, as métricas de valor da vida útil (LTV) não são compatíveis com a API Data v1.
Equivalência de métricas de coorte
A maioria das métricas de coorte definidas na API Reporting v4 pode ser substituída por uma expressão para alcançar um resultado equivalente na API Data v1, conforme o gráfico abaixo.
| Nome da métrica da API Reporting v4 | Nome ou expressão da métrica na API Data v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", além de um filtro de dimensão por eventName correspondente ao evento de conclusão de meta desejado. |
Solicitação da API Data v1
Veja a seguir um exemplo de consulta que configura um coorte de usuários cuja primeira sessão aconteceu em uma semana a partir de 03/01/2021. O número de usuários ativos e a taxa de retenção de usuários são calculados para a coorte em cinco semanas usando a granularidade SEMANAL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Resposta da API Data v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Solicitação da API Reporting v4
Veja a seguir um exemplo de consulta que configura um coorte de usuários cuja primeira sessão aconteceu em uma semana a partir de 03/01/2021. O número de usuários ativos e a taxa de retenção de usuários são calculados para o coorte ao longo de cinco semanas usando a granularidade WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Resposta da API Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Amostragem
A API Data v1 usa automaticamente a amostragem de dados quando prevê que os limites de cardinalidade reduzirão a qualidade dos dados. Se os resultados de um período forem de amostra, o metadata de RunReportResponse conterá um SamplingMetadata correspondente, semelhante ao campo samplingLevel, presente na API Reporting v4.
Atualização de dados
A API Data não tem equivalente para o campo isDataGolden da API Reporting v4, que era usado para indicar se todos os hits de um relatório foram processados. O mesmo relatório pode mostrar resultados diferentes quando consultado em uma data posterior devido ao processamento adicional.
Segmentos (incompatível)
No momento, os segmentos não são compatíveis com a API Data v1.
Relatório de tempo real
Use o método properties.runRealtimeReport da API Data v1 para gerar relatórios de tempo real para as propriedades do Google Analytics 4. O recurso de Relatório de tempo real para as propriedades do Universal Analytics era disponibilizado pelo método data.realtime.get da API Google Analytics v3.
O esquema de Relatório de tempo real da API Data é diferente do esquema da API Analytics v3 devido a diferenças conceituais entre o Universal Analytics. e o Google Analytics 4.
Solicitação da API Data v1
No exemplo a seguir, para preservar o comportamento de classificação padrão da API Google Analytics v3, um elemento orderBy opcional foi adicionado à consulta da API Data v1.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Resposta da API Data v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Solicitação da API Google Analytics v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Resposta da API Google Analytics v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
Relatórios de atividade do usuário (incompatível)
No momento, a API Data v1 não é compatível com recursos que registram as atividades de usuários individuais como o método userActivity.search da API Reporting v4.
Mudanças na cota da API
Categorias de cotas principais e de tempo real
Para fins de cota, a API Data tem duas categorias de solicitação: principal e de tempo real. As solicitações de API para métodos de relatórios principais (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) cobram cotas principais.
As solicitações de API para o método runRealtimeReport cobram cotas de tempo real.
Cotas de token
Além das cotas do projeto, cada solicitação consome cotas de token cobradas de acordo com a complexidade da consulta. Consulte a documentação de cotas da API Data v1 para uma descrição detalhada das cotas e limites da API.
Para ver o estado atual de todas as cotas de uma propriedade do Google Analytics, defina returnPropertyQuota como true em uma solicitação de relatório principal ou de tempo real. O estado da cota será retornado em PropertyQuota.
Cota com base em recursos (incompatível)
Como todos os relatórios principais do Google Analytics 4 se baseiam em dados sem amostragem, a cota com base em recursos introduzida na API Reporting v4 não é mais aplicável, e não há equivalente ao campo useResourceQuotas presente em uma solicitação de relatório da API Data v1.
Cota de solicitações por visualização (perfil) por dia (incompatível)
Como não há vistas no Google Analytics 4, a cota requests per view (profile) per day não está presente na API Data v1 e foi substituída pelas cotas de token.