Как создать отчет

Это руководство для разработчиков по Analytics Reporting API версии 4. Подробную информацию об этом API вы найдете здесь.

Отчеты

В Analytics Reporting API версии 4 для доступа к отчетам применяется метод batchGet. Ниже показано, как выглядит тело запроса для batchGet и тело ответа от batchGet.

Текст запроса

Чтобы запросить данные с помощью Analytics Reporting API версии 4, нужно создать объект ReportRequest, соответствующий следующим требованиям:

  • В поле viewId должен быть указан действительный идентификатор представления.
  • В поле dateRanges должно присутствовать хотя бы одно допустимое значение.
  • В поле metrics должно присутствовать хотя бы одно допустимое значение.

Чтобы узнать идентификатор представления, отправьте запрос методом, который выводит список сводок по аккаунту, или воспользуйтесь обозревателем аккаунтов. Если диапазон дат не указан, будет использоваться значение по умолчанию: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Пример запроса, оформленного в соответствии с минимальными требованиями:

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

Метод batchGet может принять максимум пять объектов ReportRequest. При этом в полях dateRange, viewId, segments, samplingLevel и cohortGroup у всех запросов должны быть указаны одинаковые значения.

Тело ответа

Тело ответа на запрос к API представляет собой массив объектов Report. Структура отчета определяется в объекте ColumnHeader, в котором описаны параметры и показатели отчета, а также их типы данных. Значения параметров и показателей указываются в поле data.

Пример ответа на запрос выше:

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

Показатели

Показатели – это количественные данные. В запрос нужно включить минимум один объект Metric.

В следующем примере показатель Sessions включен в метод batchGet, чтобы узнать точное число сеансов за указанный диапазон дат.

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

Список доступных параметров и показателей можно получить с помощью обозревателя или Metadata API.

Фильтрация

В запросе batchGet можно задать критерии возврата показателей. Для этого добавьте в тело запроса хотя бы одно выражение MetricFilterClause, а в каждом объекте MetricFilterClause задайте по одному или несколько фильтров MetricFilter. Для каждого объекта MetricFilter укажите значения в следующих полях:

  • metricName
  • not
  • operator
  • comparisonValue

Если вы укажете в поле {metricName} показатель, в поле {operator} – operator, а в поле {comparisonValue} – comparisonValue, результат будет таким:

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

Если в поле not вы укажете true, результат будет таким:

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

В следующем примере метод batchGet возвращает только просмотры страниц, значение которых больше 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"
          }]
      }]
  }]
}

Выражения

Выражения рассчитываются автоматически на основе существующих показателей и фактически представляют собой динамические вычисляемые показатели. Каждому выражению можно дать псевдоним. Пример:

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

Сортировка

Чтобы упорядочить результаты по значению показателя, выполните следующие действия:

  • Укажите его имя или псевдоним в поле fieldName.
  • Укажите порядок сортировки (ASCENDING или DESCENDING) в поле sortOrder.

В примере ниже метод batchGet возвращает показатели с сортировкой по сеансам и просмотрам страниц в убывающей последовательности.

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

Параметры

Параметры – это характеристики пользователей, их действий и сеансов. Например, параметр "Город" указывает город, из которого был выполнен сеанс. В запросе batchGet можно указать несколько параметров. Пример:

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

Фильтрация

В запросе batchGet можно задать критерии возврата параметров. Для этого добавьте в тело запроса хотя бы одно выражение DimensionsFilterClause, а в каждом объекте DimensionsFilterClause задайте по одному или несколько фильтров DimensionsFilters. Для каждого объекта DimensionsFilters укажите значения в следующих полях:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Если вы укажете в поле {dimensionName} параметр, в поле {operator} – operator, а в поле {expressions} – expressions, результат будет таким:

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

Если в поле not вы укажете true, результат будет таким:

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

В следующем примере метод batchGet возвращает просмотры страниц и сеансы в браузере 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"]
            }
          ]
        }
      ]
    }
  ]
}

Сортировка

Чтобы упорядочить результаты по значению параметра, выполните следующие действия:

  • Укажите его имя в поле fieldName.
  • Укажите порядок сортировки (ASCENDING или DESCENDING) в поле sortOrder.

В примере ниже метод batchGet возвращает параметры с сортировкой по стране и браузеру.

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

Поле histogramBuckets

Если параметры выражены целыми числами, для простоты анализа лучше сегментировать их значения по диапазонам. Для этого укажите границы диапазонов в поле histogramBuckets и выберите HISTOGRAM_BUCKET в качестве типа сортировки. Пример:

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

Несколько диапазонов дат

В Google Analytics Reporting API версии 4 в одном запросе можно указать несколько диапазонов дат. Независимо от их количества, данные будут возвращены в объекте dateRangeValue. Пример:

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

Сортировка с разностным подходом

Если вы запрашиваете значения показателей по диапазонам дат, результаты можно упорядочить по разнице между значениями из диапазонов. Пример:

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

Запрос параметров, связанных со временем

Если вы запросите параметр, связанный с датой или временем, в объекте DateRangeValue будут содержаться только значения, входящие в указанный вами временной диапазон. Все остальные будут равны 0.

Допустим, вы запрашиваете параметр ga:date и показатель ga:sessions по двум диапазонам дат: за январь и февраль. В ответе с данными за январь февральские значения будут равны 0. И наоборот, в ответе с данными за февраль 0 будут равны январские значения.

Отчет за январь

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

Отчет за февраль

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

Сегменты

Если вы хотите запросить набор данных Google Analytics с учетом критериев, используйте сегменты. Например, в одном сегменте можно определить пользователей из конкретной страны или города, а в другом – посетителей конкретного раздела сайта. Отличие сегментов от фильтров в том, что при установке последних возвращаются только строки, которые соответствуют условию. Сегменты же позволяют получить весь набор данных, соответствующих критериям.

Требования при составлении запроса с сегментами:

  • Во всех объектах ReportRequest, включенных в метод batchGet, сегменты должны быть определены одинаково.
  • В список параметров нужно добавить ga:segment.

Пример:

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

Другие примеры запросов с сегментами можно найти здесь.

Поле segmentId

Чтобы запросить сегменты, используйте поле segmentId. Учтите, что запрос с одновременным использованием полей segmentId и dynamicSegment невозможен.

Пример:

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

Выборка

Как правило, выборка является основной причиной расхождений между значениями, возвращаемыми из API и веб-интерфейса. Размер выборки устанавливается в поле samplingLevel.

  • Если установить значение SMALL, размер выборки и время отклика будут меньше.
  • Если установить значение LARGE, данные будут точнее, но их сбор займет больше времени.
  • Если установить значение DEFAULT, выборка будет составлена с оптимальной скоростью и точностью.

Пример:

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

Если в отчет включена выборка, Analytics Reporting API версии 4 возвращает поля samplesReadCounts и samplingSpaceSizes. Если выборки нет, они не определяются.

Ниже приведен пример ответа с выборкой, запрошенной по двум диапазонам дат. Для расчета результатов было проанализировано почти 500 тысяч примеров, а размер выборочного пространства составил около 15 млн сеансов.

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

Разбивка на страницы

В Analytics Reporting API версии 4 большие объемы результатов разбиваются на страницы с помощью полей pageToken и pageSize. Параметр nextPageToken возвращает значение поля pageToken в ответ на запрос reports.batchGet:

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

Далее

В следующем разделе рассматриваются расширенные функции API версии 4.