Запрос к API

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

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

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

https://api-metrika.yandex.net/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>]
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

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

Пример запроса


https://api-metrika.yandex.net/analytics/v3/data/ga?end-date=today&ids=ga%3A29761725&metrics=ga%3Apageviews&start-date=6daysAgo

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


{
    "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 Отображает идентификатор запроса.
selfLink Отображает ссылку на данный запрос.
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.
Параметры Описание
kind Отображает тип ресурса. Параметр всегда принимает значение analytics#gaData.
id Отображает идентификатор запроса.
selfLink Отображает ссылку на данный запрос.
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.