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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Введение

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

Запрос

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

analytics.data.ga.get()

Этот метод представлен в различных клиентских библиотеках и имеет языковые интерфейсы для установки параметров запроса.

API также можно запрашивать как конечную точку REST-ful:

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 да Дата начала получения данных Analytics. Запросы могут указывать начальную дату в формате YYYY-MM-DD или относительную дату (например, today , yesterday или NdaysAgo , где N — положительное целое число).
end-date string да Дата окончания получения данных Analytics. Запрос может указывать дату окончания в формате YYYY-MM-DD или относительную дату (например, today , yesterday или NdaysAgo , где N — положительное целое число).
metrics string да Список метрик, разделенных запятыми, например ga:sessions,ga:bounces .
dimensions string нет Список разделенных запятыми параметров для ваших данных Analytics, например ga:browser,ga:city .
sort string нет Список измерений и показателей, разделенных запятыми, указывающих порядок сортировки и направление сортировки возвращаемых данных.
filters string нет Фильтры параметров или показателей, которые ограничивают данные, возвращаемые по вашему запросу.
segment string нет Сегментирует данные, возвращаемые по вашему запросу.
samplingLevel string нет Желаемый уровень выборки. Допустимые значения:
  • DEFAULT — возвращает ответ с размером выборки, который уравновешивает скорость и точность.
  • FASTER — возвращает быстрый ответ с меньшим размером выборки.
  • HIGHER_PRECISION — возвращает более точный ответ, используя большой размер выборки, но это может привести к замедлению ответа.
include-empty-rows boolean нет По умолчанию истинно; если установлено значение 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: с идентификатором представления (профиля) Google 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-date2005-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-date2005-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 запроса filter ограничивает данные, возвращаемые вашим запросом. Чтобы использовать параметр 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 фильтрует показатель просмотров страниц.
  • оператор — определяет тип соответствия фильтра для использования. Операторы относятся либо к параметрам, либо к показателям.
  • выражение — указывает значения, которые должны быть включены или исключены из результатов. Выражения используют синтаксис регулярных выражений.

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


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

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

Фильтры можно комбинировать с помощью AND операций OR и И. Это позволяет эффективно расширить ограничение в 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, см. в Руководстве по сегментам для разработчиков.

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

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


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

samplingLevel=DEFAULT
По желанию.
Используйте этот параметр, чтобы задать уровень выборки (т. е. количество сеансов, используемых для вычисления результата) для запроса отчета. Допустимые значения соответствуют веб-интерфейсу и включают:
  • DEFAULT — возвращает ответ с размером выборки, который уравновешивает скорость и точность.
  • FASTER — возвращает быстрый ответ с меньшим размером выборки.
  • HIGHER_PRECISION — возвращает более точный ответ, используя большой размер выборки, но это может привести к замедлению ответа.
Если он не указан, будет использоваться уровень выборки DEFAULT .
Подробнее о том, как рассчитать процент сеансов, использованных для запроса, см. в разделе « Выборка ».

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

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

начальный индекс

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

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

max-results=100
По желанию.
Максимальное количество строк для включения в этот ответ. Вы можете использовать это в сочетании с start-index для получения подмножества элементов или использовать его отдельно, чтобы ограничить количество возвращаемых элементов, начиная с первого. Если max-results не указан, запрос возвращает максимум 1000 строк по умолчанию.
Analytics Core Reporting API возвращает не более 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 .


quotaUser

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 По умолчанию истинно; если установлено значение 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 .
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 Истинно, если ответ содержит выборочные данные.
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 Строки данных Analytics, где каждая строка содержит список значений параметров, за которыми следуют значения показателей. Порядок параметров и показателей такой же, как указано в запросе. В каждой строке есть список из 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 По умолчанию истинно; если установлено значение 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 .
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 Истинно, если ответ содержит выборочные данные.
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 Объект Data Table , который можно использовать с Google Charts .
dataTable.cols[] list Список дескрипторов столбцов для параметров, за которыми следуют показатели. Порядок параметров и показателей такой же, как указано в запросе через параметры metrics и dimensions . Количество столбцов — это количество параметров + количество показателей.
dataTable.cols[].id string Идентификатор, который можно использовать для ссылки на конкретный столбец (в качестве альтернативы использованию индексов столбцов). Идентификатор параметра или показателя используется для установки этого значения.
dataTable.cols[].label string Метка для столбца (которая может отображаться визуализацией). Идентификатор параметра или показателя используется для установки этого значения.
dataTable.cols[].type string Тип данных для этого столбца.
dataTable.rows[] list Строки данных Analytics в формате таблицы данных, где каждая строка представляет собой объект, содержащий список значений ячеек для параметров, за которыми следуют показатели. Порядок параметров и показателей такой же, как указано в запросе. Каждая ячейка имеет список из N полей, где N = количество измерений + количество метрик.

Коды ошибок

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

Попытайся!

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

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

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

Выборка

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

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

Если ответ Core Reporting API содержит выборочные данные, то поле ответа containsSampledData будет иметь значение true . Кроме того, 2 свойства предоставят информацию об уровне выборки для запроса: sampleSize и sampleSpace . С помощью этих двух значений вы можете рассчитать процент сеансов, использованных для запроса. Например, если sampleSize равен 201,000 , а sampleSpace220,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)