В этом документе представлен полный справочник по запросам и ответам для 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 | нет | Желаемый уровень выборки. Допустимые значения:
|
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
ga:
с идентификатором представления (профиля) Analytics. Вы можете получить идентификатор представления (профиля) с помощью метода analytics.management.profiles.list
, который предоставляет id
в ресурсе представления (профиля) в API управления Google Analytics .Дата начала
start-date= 2009-04-20
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
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
Параметр строки запроса 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
. - Чувствительность к регистру . Сопоставление регулярных выражений не учитывает регистр.
- Максимальная длина — 128 символов . Регулярные выражения длиной более 128 символов приводят к возврату с сервера кода состояния
Комбинирование фильтров
Фильтры можно комбинировать с помощью логической логики 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, см. в Руководстве для разработчиков по сегментам .
Концептуальный обзор сегментов см . в справочнике по функциям «Сегменты» и «Сегменты» в Справочном центре.
Параметры и показатели разрешены в сегментах.
Не все параметры и показатели можно использовать в сегментах. Чтобы просмотреть, какие параметры и показатели разрешены в сегментах, посетите Обозреватель параметров и показателей .
уровень выборки
samplingLevel=DEFAULT
-
DEFAULT
— возвращает ответ с размером выборки, обеспечивающим баланс скорости и точности. -
FASTER
— возвращает быстрый ответ с меньшим размером выборки. -
HIGHER_PRECISION
— возвращает более точный ответ с использованием большого размера выборки, но это может привести к замедлению ответа.
DEFAULT
.включить пустые строки
include-empty-rows=true
стартовый индекс
start-index=10
1
. (Индексы результатов отсчитываются от 1. То есть первая строка — это строка 1
, а не строка 0
) Используйте этот параметр в качестве механизма нумерации страниц вместе с параметром max-results
для ситуаций, когда totalResults
превышает 10 000 и вы хотите получить индексированные строки. от 10 001 и выше.максимальные результаты
max-results=100
start-index
для получения подмножества элементов или использовать его отдельно, чтобы ограничить количество возвращаемых элементов, начиная с первого. Если max-results
не указан, запрос возвращает максимум по умолчанию — 1000 строк.ga:country
существует менее 300 возможных значений, поэтому при сегментировании только по стране вы не сможете получить более 300 строк, даже если для параметра max-results
установлено более высокое значение.выход
output=dataTable
-
json
— выводит в ответ свойствоrows
по умолчанию, содержащее объект JSON. -
dataTable
— выводит в ответ свойствоdataTable
, содержащее объект таблицы данных . Этот объектData Table
можно использовать непосредственно с визуализациями Google Charts .
поля
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 .
{
"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 = количество измерений + количество метрик. |
{
"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),
В этом документе представлен полный справочник по запросам и ответам для 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 | да | Дата начала для получения данных аналитики. Запросы могут указать дату начала, отформатированную как YYYY-MM-DD , или как относительная дата (например, today , yesterday , или NdaysAgo , где N является положительным целым числом). |
end-date | string | да | Конец даты получения данных аналитики. Запрос может указать дату окончания, отформатированную как YYYY-MM-DD , или как относительная дата (например, today , yesterday , или NdaysAgo , где N положительное целое число). |
metrics | string | да | Список, разделенные запятыми, такие как ga:sessions,ga:bounces . |
dimensions | string | нет | Список разделенных запятых аспектов для ваших аналитических данных, таких как ga:browser,ga:city . |
sort | string | нет | Список разделенных запятых измерений и метрик, указывающих на порядок сортировки и направление сортировки для возвращенных данных. |
filters | string | нет | Измерение или метрические фильтры, которые ограничивают возвратные данные для вашего запроса. |
segment | string | нет | Сегменты данные возвращались для вашего запроса. |
samplingLevel | string | нет | Желаемый уровень отбора проб. Разрешенные значения:
|
include-empty-rows | boolean | нет | По умолчанию к истинному; Если установить на FALSE, ряды, где все значения метрики равны нулю, будут опущены из ответа. |
start-index | integer | нет | Первая строка данных для извлечения, начиная с 1. Используйте этот параметр в качестве механизма странификации вместе с параметром max-results . |
max-results | integer | нет | Максимальное количество рядов включает в ответ. |
output | string | нет | Желаемый тип вывода для аналитических данных возвращался в ответе. Приемлемые значения являются json и dataTable . По умолчанию: json . |
fields | string | нет | Селектор, указавший подмножество полей, чтобы включить в ответ. |
prettyPrint | string | нет | Возвращает ответ с помощью отступлений и разрывов линий. По умолчанию false . |
userIp | string | нет | Определяет IP -адрес конечного пользователя, для которого делается вызов API. Используется для ограничения использования на IP . |
quotaUser | string | нет | Альтернатива пользователю в случаях, когда IP -адрес пользователя неизвестен. |
access_token | string | нет | Один из возможных способов обеспечить токен OAuth 2.0 . |
callback | string | нет | Имя функции обратного вызова JavaScript, которая обрабатывает ответ. Используется в JAVAScript JSON-P запросов . |
key | string | нет | Используется для разрешения OAuth 1.0A для указания вашего приложения для получения квоты. Например: key= AldefliuhSFADSfasdfasdfASdf . |
Подробная информация о параметре запроса
идентификаторы
ids= ga:12345
ga:
Analytics View (профиль). Вы можете получить идентификатор представления (профиль), используя метод analytics.management.profiles.list
, который предоставляет id
в ресурсе View (профиль) в API Google Analytics Management .Дата начала
start-date= 2009-04-20
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
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
Параметр строки запроса 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
Filters на метрике просмотров страниц. - Оператор - определяет тип совпадения фильтра для использования. Операторы специфичны для размеров или метрик.
- Выражение - указывает значения, которые должны быть включены или исключены из результатов. Выражения используют регулярное синтаксис выражения.
Операторы фильтра
Есть шесть операторов фильтра для размеров и шесть операторов фильтра для метрик. Операторы должны быть кодированы 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~ | Совокупные метрики, где город начинается с нового :filters=ga:city%3D~%5ENew.* (%5e - это URL, закодированный от символа ^, который прикрепляет шаблон на начало строки.) |
!~ | Не соответствует регулярному выражению | !~ | Совокупные метрики, где город не начинается с нового :filters=ga:city!~%5ENew.* |
Экспрессия фильтра
Есть несколько важных правил выражения фильтра:
- Опасные для URL персонажи -такие символы, как
&
должны быть кодированы URL обычным способом. - Зарезервированные персонажи - полуколон и запятая должны быть сбежались, когда они появляются в выражении:
- точка с запятой
\;
- Компа
\,
- точка с запятой
- Регулярные выражения - вы также можете использовать регулярные выражения в выражениях фильтра, используя операторы
=~
и!~
. Их синтаксис аналогичен регулярным выражениям Perl и имеет эти дополнительные правила:- Максимальная длина 128 символов - обычные выражения более 128 символов приводят к
400 Bad Request
возвращенного с сервера. - Чувствительность случая -регулярное соответствие выражения нечувствительно.
- Максимальная длина 128 символов - обычные выражения более 128 символов приводят к
Объединение фильтров
Фильтры могут быть объединены с использованием 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
Для получения полной информации о том, как запросить сегмент в основном API отчетности, см. Руководство по сегментам DEV .
Концептуальный обзор сегментов см . В сегментах ссылки и сегменты в справочном центре.
Размеры и метрики разрешены в сегментах.
Не все измерения и метрики могут использоваться в сегментах. Чтобы рассмотреть, какие измерения и метрики разрешены в сегментах, посетите размеры и метрики .
SAMPLINGLEVEL
samplingLevel=DEFAULT
-
DEFAULT
- возвращает ответ с размером выборки, который уравновешивает скорость и точность. -
FASTER
- возвращает быстрый ответ с меньшим размером выборки. -
HIGHER_PRECISION
- возвращает более точный ответ с помощью большого размера выборки, но это может привести к тому, что ответ будет медленнее.
DEFAULT
.Включите-пустые строки
include-empty-rows=true
стартовый-индекс
start-index=10
1
. (Индексы результатов основаны на 1. То есть первая строка-строка 1
, а не строка 0
) Используйте этот параметр в качестве механизма странификации, а также параметр max-results
для ситуаций, когда totalResults
превышают 10 000, и вы хотите получить индексированные ряды на 10 001 и далее.максимум
max-results=100
start-index
для извлечения подмножества элементов или использовать его в одиночку, чтобы ограничить количество возвращаемых элементов, начиная с первого. Если max-results
не поставляются, запрос возвращает максимум по умолчанию 1000 строк.ga:country
составляет менее 300 возможных значений, поэтому, когда сегментируйте только страну, вы не можете получить более 300 строк, даже если вы устанавливаете max-results
на более высокое значение.выход
output=dataTable
-
json
- выводит свойствоrows
по умолчанию в ответе, содержащее объект JSON. -
dataTable
- выводитdataTable
в ответе, содержащее объект таблицы данных . Этот объектData Table
может быть использован непосредственно с помощью визуализаций Google диаграмм .
поля
fields=rows,columnHeaders(name,dataType)
Указывает, какие поля возвращаются в частичный ответ. Если вы используете только подмножество полей в ответе API, вы можете использовать параметр fields
, чтобы указать, какие поля включать.
Формат значения параметра запроса полей свободно основан на синтаксисе XPath. Поддерживаемый синтаксис приведен ниже.
- Используйте разделенный запятой список, чтобы выбрать несколько полей.
- Используйте
a/b
, чтобы выбрать поле B, которое вложено в поле A; Используйтеa/b/c
, чтобы выбрать поле C, вложенное в B. - Используйте подселектор, чтобы запросить набор конкретных подколов массивов или объектов, размещая выражения в скобках
"( )"
.
Например:fields=columnHeaders(name,dataType)
возвращает только поляname
иdataType
в массивеcolumnHeaders
. Вы также можете указать один подполе, гдеfields=columnHeader(name)
эквивалентнаfields=columnHeader/name
.
PrettyPrint
prettyPrint=false
Возвращает ответ в читаемом человеке формате, если true
. Значение по умолчанию: false
.
Кэтазер
quotaUser=4kh4r2h4
Позволяет обеспечить соблюдение квот на пользователя из приложения на стороне сервера даже в тех случаях, когда IP-адрес пользователя неизвестен. Это может произойти, например, с приложениями, которые запускают задания Cron в App Engine от имени пользователя. Вы можете выбрать любую произвольную строку, которая уникально идентифицирует пользователя, но она ограничена 40 символами.
Это переопределяет userIp
, если оба предоставлены.
Ответ
В случае успеха этот запрос возвращает тело ответа со структурой JSON, определенной ниже. Если выходной параметр установлен на dataTable
, то запрос возвращает корпус ответа со структурой JSON (таблица данных), определенной ниже.
ПРИМЕЧАНИЕ . Термин «результаты» относится ко всему набору строк, которые соответствуют запросу, а «ответ» относится к набору строк, возвращаемого на текущей странице результатов. Они могут быть разными, если общее количество результатов больше, чем размер страницы для текущего ответа, как объяснено в Itemsperpage .
{
"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 | Тип ресурса. Значение - «аналитика#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 . |
selfLink | string | Ссылка на эту страницу результатов для этого запроса данных. |
previousLink | string | Ссылка на предыдущую страницу результатов для этого запроса данных. |
nextLink | string | Ссылка на следующую страницу результатов для этого запроса данных. |
profileInfo | object | Информация о представлении (профиль), для которой были запрошены данные. View (профиль) Данные доступны через API Google Analytics Management. |
profileInfo.profileId | string | Просмотр (профиль) ID, такой как 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 = количество измерений + количество метрик. |
{
"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 | Тип ресурса. Значение - «аналитика#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 . |
selfLink | string | Ссылка на эту страницу результатов для этого запроса данных. |
previousLink | string | Ссылка на предыдущую страницу результатов для этого запроса данных. |
nextLink | string | Ссылка на следующую страницу результатов для этого запроса данных. |
profileInfo | object | Информация о представлении (профиль), для которой были запрошены данные. View (профиль) Данные доступны через API Google Analytics Management. |
profileInfo.profileId | string | Просмотр (профиль) ID, такой как 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 . |
dataTable.cols[] | list | Список дескрипторов столбцов для измерений, за которыми следуют метрики. Порядок измерений и метрик совпадает с указанными в запросе, посредством параметров metrics и dimensions . Количество столбцов - это количество измерений + количество метрик. |
dataTable.cols[].id | string | Идентификатор, который можно использовать для обозначения конкретного столбца (в качестве альтернативы использованию индексов столбцов). Размер или метрический идентификатор используется для установки этого значения. |
dataTable.cols[].label | string | Метка для столбца (которая может отображаться с помощью визуализации). Размер или метрический идентификатор используется для установки этого значения. |
dataTable.cols[].type | string | Тип данных для этого столбца. |
dataTable.rows[] | list | Аналитические строки данных в формате таблицы данных, где каждая строка является объектом, содержащим список значений ячеек для измерений, за которыми следуют метрики. Порядок измерений и метрик такой же, как указано в запросе. Каждая ячейка имеет список n полей, где n = количество измерений + количество метрик. |
Коды ошибок
Основной API отчетности возвращает 200
HTTP -код состояния HTTP, если запрос успешно. Если при обработке запроса возникает ошибка, API возвращает код ошибки и описание. Каждое приложение, которое использует аналитику API, должно реализовать правильную логику обработки ошибок. Для получения подробной информации о кодах ошибок и о том, как их обрабатывать, прочитайте Справочное руководство по Ошибкам .
Попробуй это!
Вы можете попробовать запросы основного API отчетности.
Чтобы увидеть действительные комбинации метрик и размеров в запросе, введите значения выборки для параметров в исследователе запроса . Результаты образца запроса показаны в виде таблицы со значениями для всех указанных метрик и измерений.
Чтобы сделать запрос на живые данные и увидеть ответ в формате JSON, попробуйте метод
analytics.data.ga.get
в API Google Data Apis Explorer .
Выборка
Google Analytics рассчитывает определенные комбинации аспектов и метрик на лету. Чтобы вернуть данные в разумное время, Google Analytics может обрабатывать только выборку данных.
Вы можете указать уровень выборки для использования для запроса, установив параметр SamplingLel .
Если основной отчетный ответ API содержит отобранные данные, то поля ответа true
containsSampledData
. Кроме того, 2 свойства предоставит информацию о уровне отбора проб для запроса: sampleSize
и sampleSpace
. С этими 2 значениями вы можете рассчитать процент сеансов, которые использовались для запроса. Например, если 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)