Como criar um relatório

Este é um guia do desenvolvedor da Reporting API v4 do Google Analytics. Para ver uma referência detalhada da API, consulte a Referência da API.

Esta documentação é referente à Reporting API v4 do Google Analytics. Para a documentação da Core Reporting API v3, consulte a Visão geral. Para migrar seu código para usar a API v4, consulte o Guia de migração.

Relatórios

A API de relatórios v4 do Google Analytics oferece o método batchGet para acessar o recurso Reports. As seções a seguir descrevem a estrutura do corpo da solicitação de batchGet e a estrutura do corpo da resposta de batchGet.

Corpo da solicitação

Para usar a Reporting API v4 do Google Analytics para solicitar dados, é necessário criar um objeto ReportRequest, que contém estes requisitos mínimos:

• um ID da vista válido para o campo viewId;
• pelo menos uma entrada válida no campo dateRanges;
• pelo menos uma entrada válida no campo metrics.

Para encontrar o código da vista, consulte o método account summaries ou use o Explorador da conta. Se um período não for fornecido, o período padrão será: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Veja a seguir uma solicitação de amostra com o mínimo de campos obrigatórios:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

O método batchGet aceita no máximo cinco objetos ReportRequest. Todas as solicitações precisam ter dateRange, viewId, segments, samplingLevel e cohortGroup.

Corpo da resposta

O corpo da resposta da solicitação da API é um conjunto de objetos Report. A estrutura de relatórios é definida no objeto ColumnHeader, que descreve as dimensões e métricas e seus respectivos tipos de dados no relatório. Os valores das dimensões e métricas são especificados no campo data.

Veja um exemplo de resposta da solicitação de amostra acima:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

Observação: se um campo booleano estiver ausente durante a análise do corpo da resposta, considere que o valor dele é false. Somente campos booleanos com valor true são exibidos na resposta. Por exemplo, o campo isDataGolden estará na resposta se o valor dele for true.

Métricas

Métricas são medidas quantitativas. Todas as solicitações requerem pelo menos um objeto Metric.

No exemplo a seguir, a métrica Sessions é fornecida ao método batchGet para mostrar o número total de sessões no período especificado:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

Você pode usar o Explorador de dimensões e métricas ou a API Metadata para ver a lista de dimensões e métricas disponíveis.

Filtragem

Ao enviar uma solicitação batchGet, você pode pedir a ela que retorne apenas métricas que atendam a critérios específicos. Para filtrar métricas, especifique um ou mais MetricFilterClauses no corpo da solicitação e, em cada MetricFilterClause, defina um ou mais MetricFilters. Em cada MetricFilter, especifique os valores de:

• metricName
• not
• operator
• comparisonValue

Permita que {metricName} represente a métrica, {operator} represente o operator e {comparisonValue} represente o comparisonValue. Então, o filtro funcionará assim:

if {metricName} {operator} {comparisonValue}
   return the metric

Se você especificar true para not, o filtro funcionará assim:

if {metricName} {operator} {comparisonValue}
   do not return the metric

No exemplo a seguir, batchGet retorna somente exibições de páginas cujo valor é maior que 2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

Expressões

Uma expressão métrica é uma expressão matemática que você define nas métricas existentes. Ela opera como métricas calculadas dinâmicas. Você pode definir um alias para representar a expressão métrica, por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

Observação: você também pode especificar os tipos de formatação das expressões métricas que definiu.

Pedidos

Para classificar os resultados pelo valor de uma métrica:

• insira o nome ou o alias dela no campo fieldName;
• especifique a ordem de classificação (ASCENDING ou DESCENDING) no campo sortOrder.

No exemplo a seguir, batchGet retorna as métricas classificadas primeiro por sessões e depois por visualizações de páginas em ordem decrescente:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

Dimensões

As dimensões descrevem as características dos seus usuários e das sessões e ações correspondentes. A dimensão "Cidade", por exemplo, descreve uma característica de sessões e indica a cidade ("Paris" ou "Nova York") de origem de cada sessão. Em uma solicitação batchGet, você pode especificar zero ou mais objetos dimension. Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

Filtragem

Ao enviar uma solicitação batchGet, você pode pedir a ela que retorne apenas dimensões que atendam a critérios específicos. Para filtrar dimensões, especifique um ou mais DimensionsFilterClauses no corpo da solicitação e defina um ou mais DimensionsFilters em cada DimensionsFilterClause. Em cada DimensionsFilters, especifique os valores de:

• dimensionName
• not
• operator
• expressions
• caseSensitive

Permita que {dimensionName} represente a dimensão, {operator} represente o operator e {expressions} represente as expressions. Então, o filtro funcionará assim:

if {dimensionName} {operator} {expressions}
    return the dimension

Se você especificar true para not, o filtro funcionará assim:

if {dimensionName} {operator} {expressions}
    do not return the dimension

No exemplo a seguir, batchGet retorna exibições de páginas e sessões em um navegador Chrome:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

Pedidos

Para classificar os resultados pelo valor de uma dimensão:

• informe o nome dela no campo fieldName;
• especifique a ordem de classificação (ASCENDING ou DESCENDING) no campo sortOrder.

Por exemplo, o batchGet a seguir retorna as dimensões classificadas por país e depois por navegador:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

Grupos de histogramas

Para dimensões com valores inteiros, é mais fácil entender as características delas agrupando os respectivos valores em intervalos. Use o campo histogramBuckets para definir os intervalos dos grupos resultantes e especifique HISTOGRAM_BUCKET como o tipo de pedido. Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

Observação: consulte o Request Composer para ver um aplicativo de demonstração que utiliza alguns desses recursos.

Vários períodos

Com a Reporting API v4 do Google Analytics, é possível ver dados de vários períodos em uma única solicitação. Independentemente de a solicitação especificar um ou dois períodos, os dados são retornados no objeto dateRangeValue. Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

Pedidos de Delta

Ao solicitar valores de métricas em dois períodos, você pode ordenar os resultados pela diferença entre os valores da métrica nos períodos, por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Comportamento da dimensão de data

Se você solicitar uma dimensão relacionada a data ou hora, o objeto DateRangeValue conterá somente valores das datas que estiverem dentro dos respectivos intervalos. Todos os demais valores que não estiverem nos períodos especificados serão 0.

Por exemplo, considere uma solicitação para a dimensão ga:date e a métrica ga:sessions em dois períodos: janeiro e fevereiro. Na resposta para os dados solicitados em janeiro, os valores em fevereiro serão 0. Já na resposta para os dados solicitados em fevereiro, os valores em janeiro serão 0.

Relatório de janeiro

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

Relatório de fevereiro

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Segmentos

Para solicitar um subconjunto dos seus dados do Google Analytics, use segmentos. Por exemplo, você pode definir os usuários de um determinado país ou cidade em um segmento e os usuários que acessarem uma parte específica do seu site em outro. Os filtros retornam somente linhas que satisfazem uma condição. Já os segmentos retornam subconjuntos de usuários, sessões ou eventos que atendem às condições que contêm os segmentos.

Ao fazer uma solicitação com segmentos:

• todas as ReportRequest em um método batchGet precisam conter definições de segmento idênticas;
• é necessário adicionar ga:segment à lista de dimensões.

Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

Consulte Amostras para ver mais exemplos de solicitações com segmentos.

ID do segmento

Use o campo segmentId para solicitar segmentos. Não é possível usar um segmentId e um dynamicSegment para solicitar segmentos.

Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

Observação: o campo segmentId também é compatível com a sintaxe de segmentos na API de relatórios principais v3. Para ver detalhes, consulte o Guia de migração.

Amostragem

Observação: para as contas do Google Analytics 360, considere a possibilidade de usar a cota com base em recursos para aproveitar limites de amostragem maiores com a API de relatórios do Google Analytics.

A amostragem pode afetar os resultados dos seus dados e é um motivo comum pelo qual os valores retornados da API não correspondem à interface da Web. Use o campo samplingLevel para definir o tamanho desejado da amostra.

• Defina o valor como SMALL para receber uma resposta rápida com tamanho de amostragem menor.
• Defina o valor como LARGE para receber uma resposta mais precisa, porém mais lenta.
• Defina o valor como DEFAULT para receber uma resposta que equilibre velocidade e precisão.

Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

Observação: todas as ReportRequest em um método batchGet precisam conter a mesma definição de samplingLevel.

Se um relatório contiver dados de amostra, a API de relatórios v4 do Google Analytics retornará os campos samplesReadCounts e samplingSpaceSizes. Se os resultados não forem de amostra, esses campos não serão definidos.

Veja a seguir um exemplo de resposta que contém dados de amostra de uma solicitação com dois períodos. Os resultados foram calculados a partir de quase 500 mil amostras do tamanho de um espaço de amostragem de aproximadamente 15 milhões de sessões:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Paginação

A API de relatórios v4 do Google Analytics utiliza os campos pageToken e pageSize para executar a paginação dos resultados em várias páginas. Você verá pageToken a partir do parâmetro nextPageToken na resposta à solicitação reports.batchGet:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

Observação: tecnicamente, nextPageToken pode ser uma string arbitrária. Porém, na maioria dos casos, ela é um índice de linhas com base em zero. Para garantir a paginação adequada, use o valor nextPageToken no campo pageToken.

Próxima etapa

Agora que você já conhece os princípios básicos da criação de um relatório, confira os recursos avançados da API v4.