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.

Relatórios

A API Reporting 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 para 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 um ID de vista, consulte o método resumos da conta ou use o Explorador da conta. Se um período não for fornecido, o 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 os mesmos dateRange, viewId, segments, samplingLevel e cohortGroup.

Corpo da resposta

O corpo da resposta da solicitação de API é uma matriz de objetos Report. A estrutura do relatório é definida no objeto ColumnHeader, que descreve as dimensões e métricas e os 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"
                        ]
                    }
                ]
            }
        }
    ]
}

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 ver 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"}]
    }
  ]
}

Use o Explorador de dimensões e métricas ou a API Metadata para conferir a lista de dimensões e métricas disponíveis.

Filtragem

Ao enviar uma solicitação batchGet, você pode pedir que ela 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} seja operator e {comparisonValue} represente 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 visualizações de página 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"
        }
      ]
    }
  ]
}

Pedidos

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

  • Forneça 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ágina 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, é possível 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 que ela retorne apenas as dimensões que atendem a critérios específicos. Para filtrar dimensões, no corpo da solicitação, especifique um ou mais DimensionsFilterClauses e, em cada DimensionsFilterClause, defina um ou mais DimensionsFilters. Em cada DimensionsFilters, especifique os valores de:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Permita que {dimensionName} represente a dimensão, {operator} represente operator e {expressions} represente 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:

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

Por exemplo, o batchGet abaixo 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"}
      ]
    }
  ]
}

Buckets do histograma

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 buckets resultantes e especifique HISTOGRAM_BUCKET como o tipo de ordem. 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"
        }
      ]
    }
  ]
}

Vários períodos

Com a API Reporting v4 do Google Analytics, é possível receber dados de vários períodos em uma única solicitação. Se a solicitação especificar um ou dois períodos, os dados serã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 se enquadrarem nos respectivos intervalos. Todos os outros 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. 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.
  • Adicione ga:segment à lista de dimensões.

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 segmentId e dynamicSegment ao mesmo tempo para solicitar segmentos.

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"}]
    }
  ]
}

Amostragem

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 da amostra desejado.

  • 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.

Exemplo:

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

Se um relatório tiver dados de amostra, a API Reporting 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 Reporting v4 do Google Analytics usa os campos pageToken e pageSize para paginar os resultados de resposta que abrangem várias páginas. Você recebe pageToken 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",
  }]
}

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.