Core Reporting API: руководство

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

Доступна новая версия Google Analytics Reporting API. Чтобы воспользоваться всеми ее преимуществами, необходимо изменить код.

Введение

Чтобы получить данные отчетов 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. Может задаваться в формате YYYY-MM-DD или относительно сегодняшнего дня. Примеры: сегодня (today), вчера (yesterday) или несколько дней назад (NdaysAgo, где N – целое положительное число).
end-date	string	Да	Дата окончания загрузки данных Google Analytics. Может задаваться в формате YYYY-MM-DD или относительно сегодняшнего дня. Примеры: сегодня (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, сервер вернет ошибку. Даты можно задавать в формате YYYY-MM-DD, а также относительно сегодняшнего дня: сегодня (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, сервер вернет ошибку. Даты можно задавать в формате YYYY-MM-DD, а также относительно сегодняшнего дня: сегодня (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

1. Синтаксис фильтра
2. Операторы фильтра
3. Выражения фильтра
4. Объединение фильтров
   • Оператор ИЛИ
   • Оператор И

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

С помощью строкового параметра filters можно ограничить возвращаемый запросом набор данных. Чтобы воспользоваться параметром 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 Bad Request;
  • чувствительность к регистру – соответствие в регулярных выражениях проверяется с учетом регистра.

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

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

ИЛИ

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

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

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

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

И

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

Примеры (во всех примерах необходимо использовать кодировку 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…

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

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

Примечание. С 27 марта 2014 года префикс dynamic:: не поддерживается. В связи с этим мы настоятельно рекомендуем как можно скорее перейти на новый синтаксис.

---

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 с таблицей данных, Этот объект Data Table можно использовать непосредственно в диаграммах Google.

По умолчанию ответ имеет формат JSON.

---

fields

fields=rows,columnHeaders(name,dataType)

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

Задает поля (fields), включаемые в частичный ответ 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	Requested sampling level.
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.
selfLink	string	Ссылка на эту страницу результатов запроса.
previousLink	string	Ссылка на предыдущую страницу результатов запроса.
nextLink	string	Ссылка на следующую страницу результатов запроса.
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	Requested sampling level.
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.
selfLink	string	Ссылка на эту страницу результатов запроса.
previousLink	string	Ссылка на предыдущую страницу результатов запроса.
nextLink	string	Ссылка на следующую страницу результатов запроса.
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, все равно потребуется постраничное разбиение. Тем не менее получение результатов даже при превышении max-results займет гораздо меньше времени. Такой подход позволяет заметно повысить эффективность как при отдельном, так и при параллельном выполнении запросов.

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

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

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

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

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