Стандартные ресурсы Universal Analytics (UA) прекратили обработку данных 1 июля 2023 года. Ресурсы UA 360 прекратят обработку данных 1 июля 2024 года, а некоторые функции UA 360 станут устаревшими до этого момента , поскольку мы перейдем на Google Analytics 4 . Используйте API данных для доступа к функциям отчетности для ресурсов GA4.

Эта страница переведена с помощью Cloud Translation API.

Базовый API отчетов — Справочное руководство

В этом документе представлен полный справочник по запросам и ответам для Core Reporting API версии 3.0.

Введение

Вы запрашиваете у Core Reporting API данные отчетов Google Analytics. Для каждого запроса требуется идентификатор представления (профиля), дата начала и окончания и хотя бы одна метрика. Вы также можете указать дополнительные параметры запроса, такие как параметры, фильтры и сегменты, для уточнения запроса. См. Обзорное руководство, чтобы понять, как все эти концепции работают вместе.

Запрос

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-адресе .

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

В следующей таблице приведены все параметры запроса, принимаемые основным API отчетов. Щелкните имя каждого параметра, чтобы просмотреть подробное описание.

Имя	Ценить	Необходимый	Краткое содержание
`ids`	`string`	да	Уникальный идентификатор таблицы в формате ga:XXXX, где XXXX — это идентификатор представления (профиля) 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`	нет	Желаемый тип вывода данных 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= ga:12345

Необходимый.

Уникальный идентификатор, используемый для получения данных Analytics. Этот идентификатор представляет собой объединение пространства имен ga: с идентификатором представления (профиля) Analytics. Вы можете получить идентификатор представления (профиля) с помощью метода analytics.management.profiles.list , который предоставляет id в ресурсе представления (профиля) в API управления Google Analytics .

Дата начала

start-date= 2009-04-20

Необходимый.

Во всех запросах данных 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 Верхний предел даты начала не ограничен.

Относительные даты всегда относятся к текущей дате на момент запроса и основаны на часовом поясе представления (профиля), указанного в запросе.

Пример диапазона дат за последние 7 дней (начиная со вчерашнего дня) с использованием относительных дат:

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

Дата окончания

end-date= 2009-05-20

Необходимый.

Самая ранняя действительная end-date — 2005-01-01 Для end-date не существует ограничения по верхнему пределу.

Пример диапазона дат за последние 10 дней (начиная с сегодняшнего дня) с использованием относительных дат:

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

размеры

dimensions= ga:browser,ga:city

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

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

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

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

метрики

metrics= ga:sessions,ga:bounces

Необходимый.

Совокупная статистика активности пользователей на вашем сайте, например кликов или просмотров страниц. Если в запросе нет параметра dimensions , возвращаемые метрики предоставляют совокупные значения для запрошенного диапазона дат, например общее количество просмотров страниц или общее количество отказов. Однако при запросе измерений значения сегментируются по значению измерения. Например, запрос ga:pageviews запрошенный с помощью ga:country возвращает общее количество просмотров страниц по стране. При запросе показателей имейте в виду:

Любой запрос должен предоставить хотя бы одну метрику; запрос не может состоять только из измерений.
Для любого запроса можно указать максимум 10 показателей.
Большинство комбинаций показателей из нескольких категорий можно использовать вместе, если не указаны параметры.
Показатель можно использовать в сочетании с другими параметрами или показателями, но только в том случае, если для этого показателя применимы допустимые комбинации. Подробности см. в Справочнике по параметрам и метрикам .

Сортировать

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 . Если ваш запрос сортируется по полю, которое не указано ни в параметрах, ни в параметрах показателей, вы получите сообщение об ошибке.
По умолчанию строки сортируются в возрастающем алфавитном порядке в локали en-US .
По умолчанию числа сортируются в порядке возрастания.
По умолчанию даты сортируются по возрастанию.

фильтры

filters=ga:medium%3D%3Dreferral

Синтаксис фильтра
Операторы фильтра
Фильтровать выражения
Комбинирование фильтров
- оператор ИЛИ
- оператор И

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

Параметр строки запроса 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

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

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

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

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

Совет . Используйте Обозреватель запросов канала данных для разработки фильтров, требующих кодирования URL-адресов, поскольку Обозреватель запросов автоматически кодирует 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`	Совокупные показатели для города Ирвин : `filters=ga:city%3D%3DIrvine`
`!=`	Не совпадает	`!%3D`	Совокупные показатели, если город не Ирвин : `filters=ga:city!%3DIrvine`
`=@`	Содержит подстроку	`%3D@`	Совокупные показатели, в которых город содержит Йорк : `filters=ga:city%3D@York`
`!@`	Не содержит подстроки	`!@`	Совокупные показатели, если в городе нет Йорка : `filters=ga:city!@York`
`=~`	Содержит совпадение с регулярным выражением	`%3D~`	Совокупные показатели, где город начинается с New : `filters=ga:city%3D~%5ENew.*` (%5E — это URL-адрес, закодированный из символа ^, который привязывает шаблон к началу строки.)
`!~`	Не соответствует регулярному выражению	`!~`	Совокупные показатели, в которых город не начинается с New : `filters=ga:city!~%5ENew.*`

Фильтровать выражения

Для выражений фильтра существует несколько важных правил:

Символы, зарезервированные URL-адресом . Такие символы, как & должны быть закодированы в URL-адресе обычным способом.
Зарезервированные символы . Точка с запятой и запятая должны быть экранированы обратной косой чертой, когда они появляются в выражении:
- точка с запятой \;
- запятая \,
Регулярные выражения . Вы также можете использовать регулярные выражения в выражениях фильтра, используя операторы =~ и !~ . Их синтаксис аналогичен регулярным выражениям Perl и содержит следующие дополнительные правила:
- Максимальная длина — 128 символов . Регулярные выражения длиной более 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 , и его МОЖНО использовать для объединения измерений и показателей в одном выражении.

Примеры: (каждый должен быть закодирован в 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=gaid::-10
 segment=sessions::condition::ga:medium%3D%3Dreferral
 segment=users::condition::ga:browser%3D%3DChrome

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

Полную информацию о том, как запросить сегмент в Core Reporting API, см. в Руководстве для разработчиков по сегментам .

Концептуальный обзор сегментов см . в справочнике по функциям «Сегменты» и «Сегменты» в Справочном центре.

Параметры и показатели разрешены в сегментах.
Не все параметры и показатели можно использовать в сегментах. Чтобы просмотреть, какие параметры и показатели разрешены в сегментах, посетите Обозреватель параметров и показателей .

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

уровень выборки

samplingLevel=DEFAULT

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

Используйте этот параметр, чтобы установить уровень выборки (т. е. количество сеансов, используемых для расчета результата) для запроса отчета. Допустимые значения соответствуют веб-интерфейсу и включают в себя:

DEFAULT — возвращает ответ с размером выборки, обеспечивающим баланс скорости и точности.
FASTER — возвращает быстрый ответ с меньшим размером выборки.
HIGHER_PRECISION — возвращает более точный ответ с использованием большого размера выборки, но это может привести к замедлению ответа.

Если он не указан, будет использоваться уровень выборки DEFAULT .

Подробную информацию о том, как рассчитать процент сеансов, использованных для запроса, см. в разделе «Выборка» .

включить пустые строки

include-empty-rows=true

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

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

стартовый индекс

start-index=10

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

Если он не указан, начальный индекс равен 1 . (Индексы результатов отсчитываются от 1. То есть первая строка — это строка 1 , а не строка 0 ) Используйте этот параметр в качестве механизма нумерации страниц вместе с параметром max-results для ситуаций, когда totalResults превышает 10 000 и вы хотите получить индексированные строки. от 10 001 и выше.

максимальные результаты

max-results=100

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

Максимальное количество строк, которые можно включить в этот ответ. Вы можете использовать это в сочетании с start-index для получения подмножества элементов или использовать его отдельно, чтобы ограничить количество возвращаемых элементов, начиная с первого. Если max-results не указан, запрос возвращает максимум по умолчанию — 1000 строк.

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

выход

output=dataTable

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

Используйте этот параметр, чтобы установить тип вывода данных Analytics, возвращаемых в ответе . Допустимые значения:

json — выводит в ответ свойство rows по умолчанию, содержащее объект JSON.
dataTable — выводит в ответ свойство dataTable , содержащее объект таблицы данных . Этот объект Data Table можно использовать непосредственно с визуализациями Google Charts .

Если он не указан, будет использоваться ответ JSON по умолчанию.

поля

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=false

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

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

quotaПользователь

quotaUser=4kh4r2h4

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

Позволяет применять квоты для каждого пользователя из серверного приложения даже в тех случаях, когда IP-адрес пользователя неизвестен. Это может произойти, например, с приложениями, которые запускают задания cron в App Engine от имени пользователя. Вы можете выбрать любую произвольную строку, которая однозначно идентифицирует пользователя, но ее длина ограничена 40 символами.

Это переопределяет userIp , если указаны оба.

Ответ

В случае успеха этот запрос возвращает тело ответа со структурой JSON, определенной ниже. Если для выходного параметра установлено значение 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`	Список измерений аналитики.
`query.metrics[]`	`list`	Список метрик аналитики.
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	По умолчанию true; если установлено значение false, строки, в которых все значения метрик равны нулю, будут исключены из ответа.
`query.sort[]`	`list`	Список метрик или измерений, по которым сортируются данные.
`query.filters`	`string`	Список фильтров метрик или параметров, разделенных запятыми.
`query.segment`	`string`	Аналитический сегмент.
`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`	Информация о представлении (профиле), для которого были запрошены данные. Данные просмотра (профиля) доступны через API управления Google Analytics.
`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`	Истинно, если ответ содержит выборочные данные.
`sampleSize`	`string`	Количество выборок, используемых для расчета выборочных данных.
`sampleSpace`	`string`	Общий размер пространства выборки. Это указывает на общий доступный размер выборочного пространства, из которого были выбраны выборки .
`columnHeaders[]`	`list`	Заголовки столбцов, в которых перечислены имена измерений, за которыми следуют имена метрик. Порядок параметров и показателей такой же, как указан в запросе через параметры `metrics` и `dimensions` . Количество заголовков – это количество измерений + количество метрик.
`columnHeaders[].name`	`string`	Название параметра или показателя.
`columnHeaders[].columnType`	`string`	Тип столбца. Либо «РАЗМЕР», либо «МЕТРИЧЕСКИЙ».
`columnHeaders[].dataType`	`string`	Тип данных. Заголовки столбцов измерения имеют только тип данных `STRING` . Заголовки столбцов метрик имеют типы данных для значений метрик, такие как `INTEGER` , `PERCENT` , `TIME` , `CURRENCY` , `FLOAT` и т. д. См. ответ API метаданных для всех возможных типов данных.
`totalsForAllResults`	`object`	Общие значения запрошенных метрик в виде пар ключ-значение имен и значений метрик. Порядок итогов показателей такой же, как порядок показателей, указанный в запросе.
`rows[]`	`list`	Строки данных аналитики, где каждая строка содержит список значений измерения, за которыми следуют значения показателей. Порядок параметров и показателей такой же, как указан в запросе. Каждая строка содержит список из N полей, где N = количество измерений + количество метрик.

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`	Список измерений аналитики.
`query.metrics[]`	`list`	Список метрик аналитики.
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	По умолчанию true; если установлено значение false, строки, в которых все значения метрик равны нулю, будут исключены из ответа.
`query.sort[]`	`list`	Список метрик или измерений, по которым сортируются данные.
`query.filters`	`string`	Список фильтров метрик или параметров, разделенных запятыми.
`query.segment`	`string`	Аналитический сегмент.
`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`	Информация о представлении (профиле), для которого были запрошены данные. Данные просмотра (профиля) доступны через API управления Google Analytics.
`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`	Истинно, если ответ содержит выборочные данные.
`sampleSize`	`string`	Количество выборок, используемых для расчета выборочных данных.
`sampleSpace`	`string`	Общий размер пространства выборки. Это указывает на общий доступный размер выборочного пространства, из которого были выбраны выборки .
`columnHeaders[]`	`list`	Заголовки столбцов, в которых перечислены имена измерений, за которыми следуют имена метрик. Порядок параметров и показателей такой же, как указан в запросе через параметры `metrics` и `dimensions` . Количество заголовков – это количество измерений + количество метрик.
`columnHeaders[].name`	`string`	Название параметра или показателя.
`columnHeaders[].columnType`	`string`	Тип столбца. Либо «РАЗМЕРЫ», либо «МЕТРИЧЕСКИЕ».
`columnHeaders[].dataType`	`string`	Тип данных. Заголовки столбцов измерения имеют только тип данных `STRING` . Заголовки столбцов метрик имеют типы данных для значений метрик, такие как `INTEGER` , `PERCENT` , `TIME` , `CURRENCY` , `FLOAT` и т. д. См. ответ API метаданных для всех возможных типов данных.
`totalsForAllResults`	`object`	Общие значения запрошенных метрик в виде пар ключ-значение имен и значений метрик. Порядок итогов показателей такой же, как порядок показателей, указанный в запросе.
`dataTable`	`object`	Объект таблицы данных , который можно использовать с Google Charts .
`dataTable.cols[]`	`list`	Список дескрипторов столбцов для параметров, за которыми следуют показатели. Порядок измерений и метрик такой же, как указан в запросе через параметры `metrics` и `dimensions` . Количество столбцов – это количество параметров + количество показателей.
`dataTable.cols[].id`	`string`	Идентификатор, который можно использовать для ссылки на определенный столбец (в качестве альтернативы использованию индексов столбцов). Идентификатор параметра или метрики используется для установки этого значения.
`dataTable.cols[].label`	`string`	Метка столбца (которая может отображаться с помощью визуализации). Идентификатор параметра или метрики используется для установки этого значения.
`dataTable.cols[].type`	`string`	Тип данных для этого столбца.
`dataTable.rows[]`	`list`	Строки данных аналитики в формате таблицы данных, где каждая строка представляет собой объект, содержащий список значений ячеек для измерений, за которыми следуют показатели. Порядок параметров и показателей такой же, как указан в запросе. Каждая ячейка имеет список из N полей, где N = количество измерений + количество метрик.

Коды ошибок

Core Reporting API возвращает код состояния HTTP 200 , если запрос успешен. Если при обработке запроса возникает ошибка, API возвращает код и описание ошибки. Каждое приложение, использующее аналитический API, должно реализовать правильную логику обработки ошибок. Подробную информацию о кодах ошибок и способах их обработки можно найти в справочном руководстве «Реакция на ошибку» .

Попробуй это!

Вы можете попробовать запросы к Core Reporting API.

Чтобы просмотреть допустимые комбинации показателей и параметров в запросе, введите образцы значений параметров в Обозревателе запросов . Результаты примера запроса отображаются в виде таблицы со значениями для всех указанных метрик и параметров.
Чтобы сделать запрос к оперативным данным и просмотреть ответ в формате JSON, попробуйте метод analytics.data.ga.get в проводнике API данных Google .

Выборка

Google Analytics рассчитывает определенные комбинации параметров и показателей на лету. Чтобы вернуть данные в разумные сроки, Google Analytics может обрабатывать только выборку данных.

Вы можете указать уровень выборки, который будет использоваться для запроса, задав параметр sampleLevel .

Если ответ Core Reporting API содержит выборочные данные, то поле ответа containsSampledData будет иметь true . Кроме того, два свойства предоставят информацию об уровне выборки для запроса: sampleSize и sampleSpace . С помощью этих двух значений вы можете рассчитать процент сеансов, использованных для запроса. Например, если sampleSize — 201,000 , а sampleSpace — 220,000 , то отчет основан на (201 000 / 220 000) * 100 = 91,36 % сеансов.

См. раздел «Выборка» для получения общего описания выборки и того, как она используется в Google Analytics.

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

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

Уменьшение размеров каждого запроса

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

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

Вместо пролистывания результатов по дате для одного длинного диапазона дат рассмотрите возможность формирования отдельных запросов для одной недели или даже одного дня. Конечно, для большого набора данных даже запрос данных за один день может вернуть больше, чем 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)