Запрос к API

Ниже описаны параметры, которые могут входить в запрос к API. Ответ возвращается в кодировке UTF-8 в виде JSON-файла.

  1. Синтаксис запроса
  2. Формат ответа

Синтаксис запроса

https://api-metrika.yandex.ru/analytics/v3/data/ga
 ? [end-date=<string>]
 & [ids=<string>]
 & [metrics=<string>]
 & [start-date=<string>]
 & [callback=<string>]
 & [dimensions=<string>]
 & [filters=<string>]
 & [max-results=<int>]
 & [samplingLevel=<g_a_sample_accuracy>]
 & [sort=<string>]
 & [start-index=<integer>]
Query-параметры
end-date

Дата окончания отчетного периода.

Вы можете указывать даты в формате YYYY-MM-DD или использовать относительные временные значения: today, yesterday, NdaysAgo.

idsНомер счетчика, данные которого необходимо получить. Перед номером счетчика необходимо указать префикс ga:.
metrics

Метрики позволяют получать данные о статистике посещаемости и активности пользователей сайта.

Если в запросе вы не укажете ни одной группировки, то API вернет общее значение метрики для выбранного временного интервала без разделения его на какие-либо группы.

Обратите внимание на следующие особенности:

  • В состав одного запроса может входить не более 10 метрик.
  • Большинство метрик можно использовать в сочетании друг с другом при условии, что не выбрана ни одна группировка.
  • Не все метрики можно сочетать с другими метриками и группировками в составе одного запроса.
start-date

Дата начала отчетного периода.

Вы можете указывать дату в формате YYYY-MM-DD или использовать относительные временные значения: today, yesterday, NdaysAgo.

Примечание.

Относительные временные значения привязаны к часовому поясу, установленному в вашей учетной записи Яндекс.Метрики.

callbackCallback. Если указан, результат будет обернут в вызов callback(...);
dimensions

Группировки объединяют данные по критериям.

Например, используйте параметр dimensions=ga:browser,ga:city, чтобы:

  1. Получить данные по количеству посещений.
  2. Сгруппировать эти данные по браузеру, который использовал посетитель и городу, в котором находился посетитель в момент посещения.

Если по указанной группировке данные не были получены, возвращается значение (not set).

Обратите внимание на следующие ограничения:

  • В состав одного запроса может входить не более 7 группировок.
  • Запрос не может состоять только из группировок, но должен содержать хотя бы одну метрику.
  • Не все группировки можно сочетать друг с другом в составе одного запроса.
filters

Фильтр позволяет ограничить данные, возвращаемые в результате запроса.

Обратите внимание на следующие особенности:

  • Фильтрация по группировке производится до использования группировок. Таким образом результирующая метрика представляет собой итоговое значение только для данных, удовлетворяющих условию группировки.
  • Фильтрация по метрике производится после использования метрик.
  • Вы можете использовать для фильтрации те группировки и метрики, которые не входят в состав вашего запроса.
max-results

Максимальное количество строк, которое будет показано в отчете.

Используйте данный параметр в сочетании с параметром start-index, чтобы получить подмножество элементов, первый из которых соответствует значению указанному в параметре start-index.

По умолчанию параметр принимает значение 100. Максимально допустимое число строк равно 10000.

Количество строк в отчете может быть меньше, чем вы указали, если для выбранного сегмента нет достаточного количества записей. Например, для группировки ga:country вы сможете получить не больше 300 записей.

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

Значение по умолчанию: DEFAULT

Допустимые значения:

  • HIGHER_PRECISION — возвращает наиболее точное значение, используя наибольшую выборку данных. Этот режим может потребовать дополнительное время и замедлить обработку запроса.
  • FASTER — возвращает быстрый результат на основе сокращенной выборки данных.
  • DEFAULT — возвращает результат на основе выборки, сочетающей скорость и точность данных.
sort

В качестве сортировки собранных данных может быть использован список метрик и группировок.

По умолчанию используется сортировка по возрастанию. Чтобы использовать сортировку по убыванию, укажите знак «-» в запросе перед списком метрик и группировок.

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

start-index

По умолчанию данный параметр принимает значение 1.

Используйте этот параметр в сочетании с параметром max-results для тех случаев, когда количество элементов списка totalResults превышает, к примеру, 10000, а вам нужно получить 10001 значение.

Примечание.

Параметр start-index отсчитывается от 1, а не от 0.

Значение по умолчанию: 1

Формат ответа


{
    "kind" :  < string > ,
    "id" :  < string > ,
    "selfLink" :  < string > ,
    "containsSampledData" :  < boolean > ,
    "sampleSize" :  < string > ,
    "sampleSpace" :  < string > ,
    "query" : {
        "start-date" :  < string > ,
        "end-date" :  < string > ,
        "dimensions" : [  < string > , ... ],
        "metrics" : [  < string > , ... ],
        "sort" : [  < string > , ... ],
        "filters" :  < string > ,
        "start-index" :  < integer > ,
        "max-results" :  < integer > 
    },
    "itemsPerPage" :  < integer > ,
    "totalResults" :  < integer > ,
    "columnHeaders" : [ {
        "name" :  < string > ,
        "columnType" :  < string > ,
        "dataType" :  < string > 
    }, ... ],
    "totalsForAllResults" : {
        "key_1" :  < string > ,
        "key_2" : ...
    },
    "rows" : [ [  < string > , ... ], ... ]
}
Параметры Описание
kind Отображает тип ресурса. Параметр всегда принимает значение analytics#gaData.
id Отображает идентификатор запроса.
containsSampledData Определяет использовалось ли семплирование при сборе данных. Если использовалось, принимает значение true.
sampleSize Отображает размер выборки, использованной для получения результата запроса с семплированием.
sampleSpace Отображает общий объем данных, доступный для осуществления выборки при использовании семплирования.
query Включает в себя все параметры, переданные в запросе.
itemsPerPage Отображает количество данных, которые отображаются на странице. По умолчанию максимальное количество данных равно 1000.
totalResults Отображает общее количество результатов.
columnHeaders Отображает заголовки столбцов, содержащих список группировок и метрик. Общее количество этих столбцов составляет общую сумму группировок и метрик, используемых в запросе.
totalsForAllResults Отображает итоговые значения запрошенных метрик, представленные в виде пар: название метрики и ее значения.
rows Отображает список строк, каждая из которых содержит измерения и метрики. Порядок данных соответствует порядку, указанному в запросе.
query
start-date Отображает дату начала отчетного периода.
end-date Отображает дату окончания отчетного периода.
dimensions Отображает список группировок запроса.
metrics Отображает список метрик запроса.
sort Отображает список метрик и группировок, по которым отсортированы данные.
filters Отображает список фильтров по метрикам и группировкам.
start-index Отображает индекс первой записи из запроса.
max-results Отображает максимальное количество строк на странице.
columnHeaders
name Содержит название группировки или метрики
columnType Содержит тип атрибута. Принимает значения: dimension или metric.
dataType Содержит тип данных. Для столбца с группировками данный параметр всегда принимает значение STRING.