Core Reporting API: справочное руководство

В этой статье описываются все запросы и ответы для Core Reporting API версии 3.0.

Введение

Чтобы получить данные отчетов Google Analytics, необходимо выполнить запрос к Core Reporting API, указав идентификатор представления (профиля), даты начала и окончания, а также хотя бы один показатель. Также можно дополнительно уточнить запрос с помощью параметров, фильтров и сегментов. Подробнее...

Запрос

В API представлен единый метод запроса данных:

analytics.data.ga.get()

Он реализован в различных клиентских библиотеках и позволяет задавать параметры запроса на различных языках.

Кроме того, запрос к API может быть выполнен из конечной точки REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Каждый параметр запроса URL определяет параметр запроса к API, который должен иметь кодировку URL.

Список параметров запроса

В этой таблице представлены все параметры запроса, принимаемые Core Reporting API. Чтобы узнать о параметре больше, нажмите на него.

Название Значение Обязательно? Описание
ids string Да Уникальный идентификатор таблицы в формате ga:XXXX, где XXXX – это идентификатор представления (профиля) Google Analytics, для которого запрос будет извлекать данные.
start-date string Да Дата начала загрузки данных Google Analytics. Может задаваться в формате ГГГГ-ММ-ДД или относительно сегодняшнего дня. Примеры: сегодня (today), вчера (yesterday) или несколько дней назад (NdaysAgo, где N – целое положительное число.
end-date string Да Дата окончания загрузки данных Google Analytics. Может задаваться в формате ГГГГ-ММ-ДД или относительно сегодняшнего дня. Примеры: сегодня (today), вчера (yesterday) или несколько дней назад (NdaysAgo, где N – целое положительное число).
metrics string Да Список разделенных запятыми показателей, например: ga:sessions,ga:bounces.
dimensions string Нет Список разделенных запятыми параметров данных Google Analytics, например: ga:browser,ga:city.
sort string Нет Список разделенных запятыми параметров и показателей, определяющий порядок и направление сортировки возвращаемых данных.
filters string Нет Фильтры параметров и показателей, ограничивающие возвращаемые запросом данные.
segment string Нет Сегментация данных, возвращаемых запросом.
samplingLevel string Нет Уровень выборки. Допустимые значения:
  • DEFAULT – оптимальное соотношение между скоростью и точностью выборки данных для запроса.
  • FASTER – быстрый ответ с меньшим размером выборки
  • HIGHER_PRECISION – точный ответ с большей выборкой и меньшей скоростью выполнения.
include-empty-rows boolean Нет По умолчанию имеет значение true. Если установлено значение false, строки с нулевыми значениями показателей исключаются из ответа.
start-index integer Нет Первая строка извлекаемых данных (начинается с 1). Используется совместно с параметром max-results для разбиения результатов на страницы.
max-results integer Нет Максимальное количество строк, включаемое в ответ.
output string Нет Выходной тип данных Google Analytics, возвращаемых в ответе. Допустимые значения: json и dataTable. Значение по умолчанию: json.
fields string Нет Селектор, определяющий набор полей, включаемых в ответ.
prettyPrint string Нет Возвращает ответ с отступами и переносами строки. Значение по умолчанию: false.
userIp string Нет Задает IP-адрес конечного пользователя, для которого выполняется вызов к API. Действует ограничение на использование для IP-адреса.
quotaUser string Нет Альтернатива параметру userIp. Используется, если IP-адрес пользователя неизвестен.
access_token string Нет Один из способов предоставить токен OAuth 2.0.
callback string Нет Название функции обратного вызова JavaScript, обрабатывающей ответ. Используется в запросах JavaScript JSON-P.
key string Нет Используется при авторизации по протоколу OAuth 1.0a для получения квоты приложением. Пример: key=AldefliuhSFADSfasdfasdfASdf.

Описание параметров запроса

ids

ids=ga:12345
Обязательный параметр.
Уникальный идентификатор, используемый для извлечения данных Google Analytics. Состоит из названия пространства имен (ga:) и идентификатора представления (профиля) Google Analytics. Чтобы извлечь идентификатор представления (профиля), используйте метод analytics.management.profiles.list, который возвращает параметр id для соответствующего ресурса в Google Analytics Management API.

К началу


start-date

start-date=2009-04-20
Обязательный параметр.
Для каждого запроса Google Analytics необходимо определить временной диапазон. Если среди параметров запроса отсутствуют start-date или end-date, сервер вернет ошибку. Даты можно задавать в формате ГГГГ-ММ-ДД, а также относительно сегодняшнего дня: сегодня (today), вчера (yesterday) и несколько дней назад (NdaysAgo) по шаблону [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Самая ранняя допустимая дата начала (start-date) – 2005-01-01. Верхний предел для параметра start-date отсутствует.
Относительные значения задаются по времени выполнения запроса с учетом часового пояса представления (профиля), для которого задан запрос.

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

  &start-date=7daysAgo
  &end-date=yesterday

К началу


end-date

end-date=2009-05-20
Обязательный параметр.
Для каждого запроса Google Analytics необходимо определить временной диапазон. Если среди параметров запроса отсутствуют start-date или end-date, сервер вернет ошибку. Даты можно задавать в формате ГГГГ-ММ-ДД, а также относительно сегодняшнего дня: сегодня (today), вчера (yesterday) и несколько дней назад (NdaysAgo) по шаблону [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Самая ранняя допустимая дата окончания (end-date) – 2005-01-01. Верхний предел для параметра end-date отсутствует.
Относительные значения задаются по времени выполнения запроса с учетом часового пояса представления (профиля), для которого задан запрос.

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

  &start-date=9daysAgo
  &end-date=today

К началу


dimensions

dimensions=ga:browser,ga:city
Необязательный параметр.
С помощью параметра dimensions можно разбить показатели по общим категориям, таким как ga:browser или ga:city. Например, общее количество просмотров страниц вашего сайта, как правило, лучше разбить по используемым браузерам. В таком случае отображается количество просмотров страниц из браузеров Firefox, Internet Explorer, Chrome и т. д.

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

  • В одном запросе можно указывать не более 7 параметров.
  • Помимо параметров в запрос обязательно включать хотя бы один показатель.
  • Некоторые сочетания параметров в одном запросе не поддерживаются. Проверить их совместимость можно с помощью специального инструмента.

К началу



metrics

metrics=ga:sessions,ga:bounces
Обязательный параметр.
Совокупные статистические показатели, описывающие активность пользователя на сайте, например количество кликов или просмотров страниц. Если в запросе не указан параметр dimensions, возвращаемые показатели будут содержать общие значения, то есть все просмотры или отказы. В остальных случаях значения будут сегментированы по заданным параметрам. Так, если заданы параметры ga:pageviews и ga:country, общее количество просмотров будет разбито по странам. При запросе показателей помните о следующем.
  • Запрос не может состоять только из параметров и должен содержать хотя бы один показатель.
  • В запросе можно указать не более 10 показателей.
  • Большинство комбинаций показателей из нескольких категорий может использоваться совместно, если не указаны параметры.
  • Показатель можно использовать в сочетании с другими совместимыми параметрами и показателями. Подробнее...

К началу



sort

sort=ga:country,ga:browser
Необязательный параметр.

Список показателей и параметров, определяющий порядок и направление сортировки возвращаемых данных.

  • Порядок сортировки определяется расположением показателей и параметров в списке (слева направо).
  • Направление сортировки по умолчанию устанавливается по возрастанию. Чтобы реализовать сортировку по убыванию, укажите в префиксе запрашиваемого поля знак минуса (-).

Сортировка результатов помогает эффективно анализировать данные. Например, чтобы определить страны с наибольшей эффективностью и популярные в них браузеры, выполните запрос с приведенным ниже параметром. В этом случае данные будут отсортированы в порядке возрастания сначала по параметру ga:country, а затем – ga:browser:

sort=ga:country,ga:browser

Чтобы определить наиболее популярные браузеры и страны, в которых они используются чаще других, выполните сортировку по возрастанию сначала по параметру ga:browser, а затем – ga:country:
sort=ga:browser,ga:country

При работе с параметром sort учитывайте следующие особенности:

  • Сортировка выполняется только по тем параметрам и показателям, которые заданы в параметрах dimensions и metrics parameters. При попытке сортировать по любому другому полю будет возвращена ошибка.
  • По умолчанию сортировка выполняется по возрастанию в алфавитном порядке согласно региональным настройкам en-US.
  • Числовые значения по умолчанию сортируются в порядке возрастания.
  • Даты по умолчанию сортируются по возрастанию.

К началу


filters

filters=ga:medium%3D%3Dreferral
Необязательный параметр.

С помощью строкового параметра filters можно ограничить возвращаемый запросом набор данных. Для этого нужно указать параметр или показатель, по которому будет выполнена фильтрация, а затем выражение фильтра. Например, в следующем коде запрашиваются те параметры ga:pageviews и ga:browser для представления (профиля) 12134, в которых значение ga:browser начинается со строки Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Запросы с фильтром ограничивают строки, которые включаются (или не включаются) в результат. Каждая строка результата проверяется на соответствие фильтру: если строка соответствует фильтру, она сохраняется, если не соответствует – удаляется.

  • Кодировка URL. Операторы фильтра автоматически кодируются клиентскими библиотеками Google API.
  • Фильтрация по параметрам. Фильтрация выполняется до их суммирования, в связи с чем возвращаемые показатели содержат общие данные только по заданным параметрам. В приведенном выше примере количество просмотров страниц представляет собой только просмотры в браузере Firefox.
  • Фильтрация по показателям. Фильтрация по показателям выполняется после их суммирования.
  • Допустимые комбинации. Можно выполнять фильтрацию по параметру или показателю, не входящему в запрос, при условии, что все параметры/показатели в запросе и в фильтре являются допустимыми комбинациями. Например, вы можете запросить список просмотров страниц за указанный период с фильтрацией по браузеру. Подробнее...

К началу

Синтаксис фильтра


Для одиночного фильтра используется следующий формат:

ga:name operator expression

В этом синтаксисе:

  • name – имя параметра или показателя, по которому производится фильтрация. Например, параметр ga:pageviews позволяет выполнить фильтрацию по количеству просмотров страниц.
  • operator – определяет тип соответствия фильтру. Операторы зависят от параметров или показателей.
  • expression – определяет значения, включаемые в результаты. В выражениях используется синтаксис регулярных выражений.

Операторы фильтра


Для параметров и показателей доступно по шесть операторов фильтра, Для включения в строки запросов URL операторы должны быть закодированы.

Совет. При работе с фильтрами используйте инструмент анализа запросов фида данных, который автоматически кодирует Explorer URL, содержащие строки и пробелы.

Фильтры показателей
Оператор Описание Форма в кодировке URL Примеры
== Равно %3D%3D Возвращает результаты, в которых время нахождения на странице точно равно десяти секундам:
filters=ga:timeOnPage%3D%3D10
!= Не равно !%3D Возвращает результаты, в которых время нахождения на странице не равно десяти секундам:
filters=ga:timeOnPage!%3D10
> Больше %3E Возвращает результаты, в которых время нахождения на странице строго больше десяти секунд:
filters=ga:timeOnPage%3E10
< Меньше %3C Возвращает результаты, в которых время нахождения на странице строго меньше десяти секунд:
filters=ga:timeOnPage%3C10
>= Больше или равно %3E%3D Возвращает результаты, в которых время нахождения на странице больше или равно десяти секундам:
filters=ga:timeOnPage%3E%3D10
<= Меньше или равно %3C%3D Возвращает результаты, в которых время нахождения на странице меньше или равно десяти секундам:
filters=ga:timeOnPage%3C%3D10

К началу

Фильтры параметров
Оператор Описание Форма в кодировке URL Пример
== Точное соответствие %3D%3D Сводные показатели для города Irvine:
filters=ga:city%3D%3DIrvine
!= Не соответствует !%3D Сводные показатели для любого города, кроме Irvine:
filters=ga:city!%3DIrvine
=@ Содержит подстроку %3D@ Сводные показатели для городов, в названии которых содержится слово York:
filters=ga:city%3D@York
!@ Не содержит подстроку !@ Сводные показатели для городов, в названии которых нет слова York:
filters=ga:city!@York
=~ Содержит совпадение для регулярного выражения %3D~ Сводные показатели для городов, название которых начинается со слова New:
filters=ga:city%3D~%5ENew.*
(%5E – это символ ^ в кодировке URL, привязывающий шаблон к началу строки.)
!~ Не соответствует регулярному выражению !~ Сводные показатели для городов, название которых не начинается со слова New:
filters=ga:city!~%5ENew..*

К началу

Выражения фильтра


Необходимо знать несколько важных правил относительно выражений фильтра.

  • Недопустимые в URL символы. Недопустимые символы, такие как &, должны быть закодированы обычным способом.
  • Зарезервированные символы. При использовании в выражениях точки с запятой, запятой и обратной косой черты перед ними необходимо ставить символ обратной косой черты.
    • точка с запятой: \;
    • запятая: \,
    • обратная косая черта: \\
  • Регулярные выражения. В выражения фильтров можно добавлять регулярные выражения с помощью операторов =~ и !~. Их синтаксис аналогичен регулярным выражениям Perl. Кроме того, для них действуют следующие дополнительные правила:
    • максимальная длина не более 128 символов – если регулярное выражение содержит больше символов, сервер возвращает код статуса 400 Неверный запрос;
    • чувствительность к регистру – соответствие в регулярных выражениях проверяется с учетом регистра.

Объединение фильтров


Фильтры можно объединять с помощью логических операторов ИЛИ и И. Это позволяет составить выражение фильтра длиной до 128 символов.

ИЛИ

В качестве оператора ИЛИ используется запятая (,). Этот оператор имеет приоритет над оператором И, и его НЕЛЬЗЯ использовать для объединения параметров и показателей в одном выражении.

Примеры (во всех примерах необходимо использовать кодировку URL)

Страной является США ИЛИ Канада:
ga:country==United%20States,ga:country==Canada

Пользователи Firefox на ОС Windows ИЛИ Macintosh:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

И

В качестве оператора И используется точка с запятой (;). Оператор ИЛИ имеет приоритет над оператором И, который МОЖНО использовать для объединения параметров и показателей в одном выражении.

Примеры (во всех примерах необходимо использовать кодировку URL)

Страной является США И используется браузер Firefox:
ga:country==United%20States;ga:browser==Firefox

Страной является США И название языка не начинается со строки en:
ga:country==United%20States;ga:language!~^en..*

Операционная система Windows ИЛИ Macintosh И браузер Firefox ИЛИ Chrome:
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

Страной является США, И количество сеансов превышает 5:
ga:country==United%20States;ga:sessions>5

К началу



segment

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Необязательный параметр.

Подробнее о том, как запросить сегмент в Core Reporting API...

Также советуем ознакомиться со справкой по сегментам и соответствующей статьей нашего Справочного центра.

Какие параметры и показатели можно использовать в сегментах
Подробнее о том, какие параметры и показатели можно использовать в сегментах, читайте здесь.

К началу


samplingLevel

samplingLevel=DEFAULT
Необязательное поле.
Задает уровень выборки для запроса отчетов, то есть количество сеансов, на основе которых рассчитывается результат. Поддерживаются те же значения, что и в веб-интерфейсе:
  • DEFAULT – оптимальное соотношение между скоростью и точностью выборки данных для запроса.
  • FASTER – быстрый ответ с меньшим размером выборки.
  • HIGHER_PRECISION – точный ответ с большей выборкой и меньшей скоростью выполнения.
По умолчанию задается уровень выборки DEFAULT.
Подробнее о расчете доли сеансов, обрабатываемой запросом...

К началу


include-empty-rows

include-empty-rows=true
Необязательный параметр.
По умолчанию имеет значение true. Если установлено значение false, строки с нулевыми значениями показателей исключаются из ответа. Например, если вы добавили в запрос несколько показателей, из него будут удалены только те строки, в которых значения всех параметров равны нулю. Это может быть полезно, когда предполагается, что допустимых строк в ответе будет намного меньше, чем значений параметров.

К началу


start-index

start-index=10
Необязательное поле.
Если начальный индекс не указан, он имеет значение 1, от которого отсчитываются все результаты. Таким образом, индекс первой строки равен 1, а не 0. Этот параметр используется совместно с параметром max-results для разбиения результатов на страницы, если их общее количество (totalResults) превышает 10 000, и вам нужно извлечь строки с последующими индексами.

К началу


max-results

max-results=100
Необязательное поле.
Максимальное количество строк, включаемое в отчет. Может использоваться вместе с параметром start-index для извлечения подмножества элементов, а также отдельно, ограничивая количество возвращаемых элементов (начиная с первого). Если параметр max-results не задан, по умолчанию запрос возвращает не более 1000 строк.
Analytics Core Reporting API, независимо от заданного ограничения, возвращает не более 10 000 строк на запрос. Если сегментов недостаточно, строк будет возвращено меньше. Например, параметр ga:country не может иметь более 300 значений, поэтому при большем значении max-results и сегментировании только по стране будет в любом случае возвращено не более 300 строк.

К началу


output

output=dataTable
Необязательное поле.
Задает тип выходных данных Google Analytics, возвращаемых в ответе. Допустимые значения:
  • json – ответ содержит стандартное свойство rows с объектом JSON.
  • dataTable – ответ содержит свойство dataTable с таблицей данных, которую можно использовать непосредственно в диаграммах Google.
По умолчанию ответ имеет формат JSON.

К началу


fields

fields=rows,columnHeaders(name,dataType)
Необязательное поле.

Задает поля, включаемые в частичный ответ API.

Формат значения параметра запроса fields основан на синтаксисе XPath. Его основные принципы перечислены ниже.

  • Чтобы выбрать несколько полей, перечислите их через запятую.
  • Используйте a/b для выбора поля b, расположенного внутри поля a; используйте a/b/c для выбора поля c, расположенного внутри поля b.
  • Используйте подселектор, чтобы запросить набор определенных подполей массивов или объектов. Для этого поместите выражения в скобки: "( )".
    Пример: fields=columnHeaders(name,dataType) возвращает только поля name и dataType в массиве columnHeaders. Также вы можете указать отдельное подполе, где fields=columnHeader(name) эквивалентно fields=columnHeader/name.

К началу


prettyPrint

prettyPrint=false
Необязательное поле.

Возвращает ответ в удобном для пользователя формате, если значение равно true. Значение по умолчанию: false.

К началу


quotaUser

quotaUser=4kh4r2h4
Необязательный параметр.

Позволяет извлечь пользовательские квоты из приложения на стороне сервера, даже если IP-адрес пользователя неизвестен (например, если приложение от имени пользователя выполняет задания с экономией времени на платформе Google App Engine). Вы можете выбрать любую строку, уникально идентифицирующую пользователя, однако ее длина не должна превышать 40 символов.

Если задан вместе с параметром userIp, то переопределяет его.

К началу


Ответ

В случае успеха этот запрос возвращает тело ответа в формате JSON со следующей структурой. Если параметру output присвоено значение dataTable, запрос возвращает тело ответа со структурой таблицы данных JSON, которая определена ниже.

Примечание. Под результатами понимаются все строки, соответствующие запросу. Ответ – это набор строк, возвращаемый на текущей странице результатов. Если общее число результатов превышает размер страницы, эти значения могут отличаться. Подробнее читайте в описании параметра itemsPerPage.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

К началу


Поля ответа

Структура тела ответа имеет следующие свойства:

Название свойства Значение Описание
kind string Тип ресурса. Значение: analytics#gaData.
id string Идентификатор ответа с данными.
query object Этот объект содержит все значения, переданные в запрос в качестве параметров. Значение каждого поля раскрывается в описании соответствующего параметра запроса.
query.start-date string Дата начала.
query.end-date string Дата окончания.
query.ids string Уникальный идентификатор таблицы.
query.dimensions[] list Список параметров Google Analytics.
query.metrics[] list Список показателей Google Analytics.
query.samplingLevel string Запрошенный уровень выборки.
query.include-empty-rows boolean По умолчанию имеет значение true. Если установлено значение false, строки с нулевыми значениями показателей исключаются из ответа.
query.sort[] list Список показателей и параметров, на основе которого сортируются данные.
query.filters string Список разделенных запятыми фильтров по показателям или измерениям.
query.segment string Сегмент Google Analytics.
query.start-index integer Начальный индекс.
query.max-results integer Максимальное количество результатов на странице.
startIndex integer Начальный индекс строки для параметра start-index. Значение по умолчанию: 1.
itemsPerPage integer Максимальное количество строк, которые может содержать ответ, независимо от фактически возвращаемого количества строк. Если задан параметр max-results, значение параметра itemsPerPage должно быть меньше max-results или 10 000. Значение параметра itemsPerPage по умолчанию: 1000.
totalResults integer Общее количество строк в результатах запроса, независимо от количества строк, возвращаемых в ответе. Для запросов, содержащих большое количество строк, значение totalResults может быть больше itemsPerPage. Подробнее о параметрах totalResults и itemsPerPage для крупных запросов читайте в разделе Разбиение на страницы.
startDate string Дата начала для запроса данных, задаваемая параметром start-date.
endDate string Дата окончания для запроса данных, задаваемая параметром end-date.
profileInfo object Сведения о представлении (профиле), для которого были запрошены данные. Эта информация предоставляется с помощью Google Analytics Management API.
profileInfo.profileId string Идентификатор представления (профиля), например 1174.
profileInfo.accountId string Идентификатор аккаунта, которому принадлежит представление (профиль), например 30481.
profileInfo.webPropertyId string Идентификатор веб-ресурса, с которым связано представление (профиль), например UA-30481-1.
profileInfo.internalWebPropertyId string Внутренний идентификатор веб-ресурса, с которым связано представление (профиль), например UA-30481-1.
profileInfo.profileName string Название представления (профиля).
profileInfo.tableId string Идентификатор таблицы представления (профиля), состоящий из префикса ga: и идентификатора самого представления (профиля).
containsSampledData boolean Имеет значение true, если запрос содержит выборку данных.
sampleSize string Количество образцов, используемое для выборки.
sampleSpace string Общий размер выборочного пространства, из которого отбираются образцы.
columnHeaders[] list Заголовки столбцов с названиями параметров и показателей в том порядке, в котором они определены с помощью параметров запроса metrics и dimensions. Количество заголовков соответствует общему количеству параметров и показателей.
columnHeaders[].name string Название параметра или показателя.
columnHeaders[].columnType string Тип столбца. Допустимые значения: DIMENSION или METRIC.
columnHeaders[].dataType string Тип данных. Заголовки столбцов параметров могут иметь только тип STRING. Заголовки столбцов показателей могут иметь такие типы значений, как INTEGER, PERCENT, TIME, CURRENCY, FLOAT и т. д. Список допустимых атрибутов…
totalsForAllResults object Итоговые значения запрошенных показателей в виде пар, состоящих из ключа (название показателя) и значения. Порядок итоговых значений соответствует порядку показателей, заданному в запросе.
rows[] list Строки данных Google Analytics, каждая из которых содержит значения параметров и показателей. Порядок параметров и показателей соответствует заданному в запросе. Количество полей в каждой строке соответствует общему количеству параметров и показателей.
Таблица данных JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

К началу


Поля ответа

Структура тела ответа имеет следующие свойства:

Название свойства Значение Описание
kind string Тип ресурса. Значение: analytics#gaData.
id string Идентификатор ответа с данными.
query object Этот объект содержит все значения, переданные в запрос в качестве параметров. Значение каждого поля раскрывается в описании соответствующего параметра запроса.
query.start-date string Дата начала.
query.end-date string Дата окончания.
query.ids string Уникальный идентификатор таблицы.
query.dimensions[] list Список параметров Google Analytics.
query.metrics[] list Список показателей Google Analytics.
query.samplingLevel string Запрошенный уровень выборки.
query.include-empty-rows boolean По умолчанию имеет значение true. Если установлено значение false, строки с нулевыми значениями показателей исключаются из ответа.
query.sort[] list Список показателей и параметров, на основе которого сортируются данные.
query.filters string Список разделенных запятыми фильтров по показателям или измерениям.
query.segment string Сегмент Google Analytics.
query.start-index integer Начальный индекс.
query.max-results integer Максимальное количество результатов на странице.
startIndex integer Начальный индекс строки для параметра start-index. Значение по умолчанию: 1.
itemsPerPage integer Максимальное количество строк, которые может содержать ответ, независимо от фактически возвращаемого количества строк. Если задан параметр max-results, значение параметра itemsPerPage должно быть меньше max-results или 10 000. Значение параметра itemsPerPage по умолчанию: 1000.
totalResults integer Общее количество строк в результатах запроса, независимо от количества строк, возвращаемых в ответе. Для запросов, содержащих большое количество строк, значение totalResults может быть больше itemsPerPage. Подробнее о параметрах totalResults и itemsPerPage для крупных запросов читайте в разделе Разбиение на страницы.
startDate string Дата начала для запроса данных, задаваемая параметром start-date.
endDate string Дата окончания для запроса данных, задаваемая параметром end-date.
profileInfo object Сведения о представлении (профиле), для которого были запрошены данные. Эта информация предоставляется с помощью Google Analytics Management API.
profileInfo.profileId string Идентификатор представления (профиля), например 1174.
profileInfo.accountId string Идентификатор аккаунта, которому принадлежит представление (профиль), например 30481.
profileInfo.webPropertyId string Идентификатор веб-ресурса, с которым связано представление (профиль), например UA-30481-1.
profileInfo.internalWebPropertyId string Внутренний идентификатор веб-ресурса, с которым связано представление (профиль), например UA-30481-1.
profileInfo.profileName string Название представления (профиля).
profileInfo.tableId string Идентификатор таблицы представления (профиля), состоящий из префикса ga: и идентификатора самого представления (профиля).
containsSampledData boolean Имеет значение true, если запрос содержит выборку данных.
sampleSize string Количество образцов, используемое для выборки.
sampleSpace string Общий размер выборочного пространства, из которого отбираются образцы.
columnHeaders[] list Заголовки столбцов с названиями параметров и показателей в том порядке, в котором они определены с помощью параметров запроса metrics и dimensions. Количество заголовков соответствует общему количеству параметров и показателей.
columnHeaders[].name string Название параметра или показателя.
columnHeaders[].columnType string Тип столбца. Допустимые значения: DIMENSION или METRIC.
columnHeaders[].dataType string Тип данных. Заголовки столбцов параметров могут иметь только тип STRING. Заголовки столбцов показателей могут иметь такие типы значений, как INTEGER, PERCENT, TIME, CURRENCY, FLOAT и т. д. Список допустимых атрибутов…
totalsForAllResults object Итоговые значения запрошенных показателей в виде пар, состоящих из ключа (название показателя) и значения. Порядок итоговых значений соответствует порядку показателей, заданному в запросе.
dataTable object Объект таблицы данных, совместимый с диаграммами Google.
dataTable.cols[] list Список дескрипторов параметров и показателей в том порядке, в котором они определены с помощью параметров metrics и dimensions запроса. Количество столбцов соответствует общему количеству параметров и показателей.
dataTable.cols[].id string Идентификатор, позволяющий ссылаться на конкретный столбец (вместо индекса). Это значение задается на основе идентификатора параметра или показателя.
dataTable.cols[].label string Ярлык столбца, который может использоваться при визуализации. Это значение задается на основе идентификатора параметра или показателя.
dataTable.cols[].type string Тип данных столбца.
dataTable.rows[] list Строки данных Google Analytics в формате таблицы. Каждая строка представляет собой объект со списком значений ячеек параметров и показателей в том порядке, в котором они определены с помощью параметров запроса. Количество полей в ячейке соответствует общему количеству параметров и показателей.

К началу

Коды ошибок

После успешного выполнения запроса Core Reporting API возвращает код статуса HTTP 200, а в случае ошибки – ее код и описание. В каждом приложении, работающем с Google Analytics API, должны быть реализованы функции обработки ошибок. Подробнее...

Попробуйте!

Ознакомьтесь с различными примерами запросов к Core Reporting API.

  • Чтобы просмотреть допустимые сочетания параметров и показателей в запросе, введите возможные значения в этот инструмент. Результаты такого запроса отображаются в виде таблицы со значениями всех указанных параметров и показателей.

  • Чтобы запросить реальные данные и просмотреть ответ в формате JSON, попробуйте метод analytics.data.ga.get в Google Data API Explorer.

Выборка

Некоторые комбинации параметров и показателей вычисляются в Google Analytics в момент запроса. Иногда, чтобы не выйти за временные рамки ответа, Google Analytics обрабатывает лишь определенную выборку данных.

Уровень выборки можно задать с помощью параметра samplingLevel.

В ответе Core Reporting API, содержащем выборку, поле containsSampledData имеет значение true. Уровень выборки задается с помощью свойств sampleSize и sampleSpace, на основе которых можно рассчитать долю сеансов, которая использовалась в запросе. Например, при значениях sampleSize=201,000 и sampleSpace=220,000 отчет будет построен на основе (201000 / 220000) * 100 = 91,36% сеансов.

Подробнее о выборке...

К началу


Обработка результатов с большим объемом данных

Из этого раздела вы узнаете, как избежать ошибок и превышения квот, а также оптимизировать запросы к API, которые могут возвращать большой объем данных. Чтобы обеспечить приемлемую эффективность, в одном запросе допускается использовать не более 7 параметров и 10 показателей, однако зачастую этого оказывается недостаточно. Вместо этого для повышения эффективности результатов можно использовать указанные ниже способы.

Уменьшение количества параметров в запросе

В одном запросе к API можно задавать до 7 параметров. При большом количестве результатов его выполнение может занимать длительное время. Например, при запросе ключевых слов по городу с разбивкой по часам может возвращаться несколько миллионов строк. Чтобы повысить эффективность, можно уменьшить их количество, убрав некоторые параметры из запроса.

Разделение запроса по диапазону дат

Вместо постраничного просмотра результатов для разных дат из одного большого диапазона можно создать отдельные запросы для одной недели – или даже для одного дня – за раз. Если количество результатов, возвращаемых запросом, превышает max-results, потребуется их постраничное разбиение. Чтобы дополнительно ограничить объем данных, мы рекомендуем сузить целевой диапазон дат. Такой подход позволяет заметно повысить эффективность как при отдельном, так и при параллельном выполнении запросов.

Разбиение на страницы

Просмотр результатов по страницам может быть полезен для разбиения больших наборов данных на удобные части. В поле totalResults указывается общее количество подходящих строк, а параметр itemsPerPage ограничивает их количество в результатах запроса. Если соотношение между totalResults и itemsPerPage достаточно велико, отдельные запросы могут выполняться слишком долго. В таком случае можно явно ограничить размер ответа с помощью параметра max-results. Тем не менее, если требуется обрабатывать весь возвращаемый объем данных, зачастую эффективнее будет запрашивать максимально допустимое количество строк.

Использование GZIP

Сжатие GZIP позволяет легко сократить требования к пропускной способности при выполнении запросов. Извлечение результатов из архива оказывает дополнительную нагрузку на процессор, однако экономия сетевых ресурсов того стоит. Чтобы получить ответ в архиве GZIP, необходимо, во-первых, задать заголовок Accept-Encoding, а во-вторых – добавить в агент пользователя строку gzip. Вот пример правильного оформления заголовков HTTP, которое обеспечивает сжатие GZIP:

Accept-Encoding: gzip
User-Agent: my program (gzip)

К началу