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

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

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

Введение

Вы запрашиваете у 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

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

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

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

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

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

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

• имя — имя параметра или метрики для фильтрации. Например: фильтры 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)