Введение
Меня зовут Андрей Устьянцев, я ведущий аналитик направления Big Data в Лиге Цифровой Экономики. Эту статью я задумал как вторую в цикле материалов (первую об улучшении лендинга на основе метрик вы можете прочитать здесь). Сам текст будет полезен аналитикам, которым необходим более глубокий анализ данных о посетителях сайта, чем предоставляет стандартный интерфейс «Яндекс.Метрики». Или тем, кто хочет объединить данные из «Метрики» с другими источниками (например, из CRM) для визуализации, поиска инсайтов, проверки продуктовых гипотез etc.
Мини-оглавление
Получение OAuth-токена
Python-код
Если у вас уже есть OAuth-токен, можете сразу переходить к разделу 2.
Получение OAuth-токена
Переходим в «Яндекс.Метрику».
Важно:
Необходимо залогиниться в «Яндекс.Метрике» под той учетной записью, которой предоставлен доступ к счетчикам, из которых необходимо получить данные.
В настройках доступа к статистике счетчика обязательно должен быть включен публичный доступ.
Нажимаем на API в верхнем меню.
Выбираем «Получить OAuth-токен».
В поле «Название вашего сервиса» вводите удобное и понятное вам название (по нему потом можно будет найти токен в общем списке).
Ставите галочку напротив «Веб-сервисы».
Переходите в поле Redirect URL и в появляющейся подсказке выбираете вариант «Подставить URL для отладки».
1. В разделе «Доступ к данным» в поле ввода начинаете вводить слово «Метрика».
2. Выбираете из выпадающего списка вариант «Получение статистики, чтение параметров своих и доверенных источников».
В поле «Почта для связи» рекомендую указать свой реальный электронный ящик. На него будут приходить информационные сообщения от «Яндекс.Метрики».
После следует нажать на кнопку «Создать приложение».
Должна появиться вот такая картинка:
Обратите внимание на «Время жизни токена», то есть срок его действия. Через год с момента создания вы не сможете получать данные из «Яндекс.Метрики» по API с использованием этого токена — необходимо будет или его актуализировать, или создать новый.
На момент написания материала токены создавались сроком действия 1 год, но все может измениться. Отчасти и по этой причине я рекомендовал выше указывать контактный адрес электронной почты (не исключено, что сервисы «Яндекса» заранее предупредят вас по почте о приближении срока окончания действия токена).
Откройте «Блокнот» или любой другой текстовый редактор и скопируйте туда ClientID.
Важно! Если такая картинка не появилась (были у меня случаи, когда на завершающей стадии регистрации появлялся пустой экран), без паники — переходим по этому адресу.
В списке приложений кликаем на только что созданное вами приложение (1 на картинке ниже) и получаем экран с нужной нам информацией:
Примечание: список ранее созданных вами приложений всегда можно найти в разделе «Мои приложения» (2 на картинке выше)
Далее в текстовом редакторе надо сформировать URL-строку такого вида:
https://oauth.yandex.ru/authorize?response_type=token&client_id=XXXXX
Замените символы «ХХХХХ» на ClientID, который вы скопировали на предыдущем шаге.
Должен получиться URL-адрес следующего вида:
https://oauth.yandex.ru/authorize?response_type=token&client_id=36d5c6d7fa432fa5f81e726bb3fa
Полученный URL-адрес вставляете в адресную строку браузера в новой вкладке и переходите по этой ссылке.
На появившемся экране следует нажать кнопку «Войти как».
Должна появиться такая картинка. Практически по центру экрана будет нужный нам OAuth-токен (далее по тексту буду использовать более привычный термин «API-ключ»).
Важно! Может отобразиться пустая страница без OAuth-токена. Без паники! Нажмите на клавиатуре Ctrl+U (или иным способом перейдите в режим просмотра кода страницы) и найдите поиском (обычно это комбинация клавиш Ctrl+F) символы «access_token».
Скопируйте себе в отдельный файл все символы, начиная с «=» до ближайшего значка «&» — это и будет ваш API-ключ.
Важно! Без необходимости никому не передавайте API-ключ — он позволяет получать доступ к статистике всех доступных вам счетчиков «Яндекс.Метрики».
Пишем Python-код для получения данных из «Яндекс.Метрики»
Для получения данных из «Яндекс.Метрики» по API нам понадобится только библиотека requests. Обычно она есть в стандартном пакете с Python, но если у вас ее нет, установите - pip install requests.
Получение сводных данных
Получим из «Яндекс.Метрики» сводные данные об источниках посетителей сайта за последние 7 дней.
import requests
API_URL = 'https://api-metrika.yandex.ru/stat/v1/data.csv'
API_token = 'y0_AgCO_AIAAn8ZwAAAADkWiTPkxy-d9aXTJElsmFx2XC840'
params = {
'date1': '6daysAgo',
'date2': 'today',
'id': 77963344,
'metrics': 'ym:s:visits,ym:s:users',
'dimensions': 'ym:s:TrafficSource',
'limit': 100
}
r = requests.get(API_URL, params = params, headers={'Authorization':API_token})Рассмотрим код детально.
Строка 3 — адрес API «Яндекс.Метрики», который возвращает данные в табличном виде.
Строка 4 — API-ключ, который мы получили на предыдущем шаге.
Строки 6-12 — параметры запроса. Далее рассмотрим подробнее.
Строки 7 и 8 — диапазон дат, за которые необходимы данные: «date1» — дата «от», «date2» — дата «до».
В приведенном примере указаны следующие значения:
«today» — служебное значение, понимается «Яндекс.Метрикой» как текущая дата.
«6daysAgo» — служебное значение, обозначающее «6 дней назад от текущей даты».
На самом деле это значения параметров «date1» и «date2» по умолчанию. То есть если вы не укажете их значения в переменной «params», «Яндекс.Метрика» вернет данные за последние 7 дней (включая текущую дату).
Кроме того, вы можете использовать обозначения:
«yesterday» — служебное обозначение даты «вчера».
«NdaysAgo» — N дней назад, считая от текущей даты (N — обязательно число).
Помимо этого, можно указать конкретные даты в формате «YYYY-MM-DD»:
«YYYY» — 4 символа, год (важно прописать полностью).
«MM» — 2 символа, номер месяца (настоятельно рекомендую не пропускать «0» в месяцах с одним числом)
«DD» –- 2 символа, день.
То есть данные за 01.06.2023 необходимо в параметрах указать как «2023-06-01».
Строка 9 — номер счетчика «Яндекс.Метрики», из которого необходимо получить данные.
Совет: номер нужного счетчика можно посмотреть через браузер в списке доступных вам счетчиков по этому адресу.
Строка 10 — обязательный параметр «metrics», метрики — числовые значения, которые необходимо получить.
«ym:s:visits» — обозначает количество визитов («визиты» — в терминах «Яндекс.Метрики»).
«ym:s:users» — «количество уникальных посетителей».
Вы можете использовать до 20 метрик в запросе.
Строка 11 — обязательный параметр «dimensions» — группировки.
В приведенном примере я выбрал только одну группировку — «ym:s:TrafficSource». Это означает «источники трафика», но вы можете указать через запятую до 10 группировок в запросе.
Полный список метрик и измерений (группировок), которые можно получить, смотрите в официальной документации «Яндекс.Метрики».
Совет: как я не путаюсь, где метрики, а где группировки? Переформулируем задачу тестового примера: «получить количество (это «метрики») посетителей сайта в разрезе (это «группировки») источников трафика».
Строка 12 — указывает, что количество возвращаемых строк должно быть не более 100.
Если вы не передадите в параметрах значение «limit», «Яндекс.Метрика» вернет не более 100 строк. Но я лично рекомендую принудительно указывать это значение, нежели потом недополучить данные и тратить время на поиск причин (или, что хуже, сделать неверные выводы из неполных данных).
Максимальное значение этого параметра — 100 000. Если в вашей задаче предполагается большее количество данных, дополнительно используйте параметр «offset» (порядковый номер выборки с шагом «limit»).
Строка 15 — вызов API «Яндекс.Метрики» для получения данных.
В случае успешного обращения r.text будет содержать следующую строку, по сути — данные в формате CSV:
Примечание: если вам привычнее или необходимо работать с данными в формате JSON, отредактируйте строку 3 кода: уберите символы «.csv» - вызывайте API по следующему адресу:
https://api-metrika.yandex.ru/stat/v1/data
В случае ошибки выполнения запроса в тексте ответа будет достаточно подробная информация о ее причине. Для примера: в параметре «date1» вместо «6daysAgo» я написал «NaysAgo». Текст ошибки, в общем-то, позволяет понять, что не так.
Теперь важный момент! Когда вы смотрите данные на сайте «Яндекс.Метрики», во всех отчетах отображаются данные без учета статистик, которые формируются при посещении сайта поисковыми и иными техническими роботами.
А данные, возвращаемые API «Яндекс.Метрики», по умолчанию содержат всю информацию, в том числе с учетом «роботов». Разница может быть достаточно ощутимой — вот пример одного из реальных счетчиков.
Лично я затрудняюсь ответить на вопрос, в какой истории может понадобиться детальная аналитика по роботам, поэтому настоятельно рекомендую во всех запросах к API «Яндекс.Метрики» в параметре «filters» в явном виде указывать, что необходимы данные без учета роботов:
'filters' : "ym:s:isRobot=='No'"
Ниже приведен полный код. В строке 12 добавлена строка с фильтрацией данных «без роботов».
import requests
API_URL = 'https://api-metrika.yandex.ru/stat/v1/data.csv'
API_token = 'y0_AgAAAIAAn8ZwAAAADkWiTPkxy-d9aXTRyE7SJEx2XC840'
params = {
'date1': '6daysAgo',
'date2': 'today',
'id': 77963344,
'metrics': 'ym:s:visits,ym:s:users',
'dimensions': 'ym:s:TrafficSource',
'filters' : "ym:s:isRobot=='No'",
'limit': 100
}
r = requests.get(API_URL, params = params, headers={'Authorization':API_token})К слову о фильтрации. В параметре «filters» можно указать и другие ограничения на выборки, причем сложные (с использованием логических операторов «И», «ИЛИ», «НЕ»). Полная документация по синтаксису фильтров — тут.
Приведенный пример получения данных достаточно простой. Полная официальная документация по API-методу «data» — здесь.
Получение данных в динамике по датам
Итак, мы разобрались, как получать сводные данные за определенный период. А если необходимы данные в динамике по дням?
Для этого следует обращаться к API «Яндекс.Метрики» по адресу:
https://api-metrika.yandex.ru/stat/v1/data/bytime
Вот пример кода. Рассмотрим только отличия от предыдущего.
import requests
API_URL = 'https://api-metrika.yandex.ru/stat/v1/data/bytime.csv'
API_token = 'y0_AgAAAAACO_AIAAn8ZwADkWiTPkxy-d9aXTRyEsmFx2XC840'
params = {
'date1': '6daysAgo',
'date2': 'today',
'id': 77963344,
'metrics': 'ym:s:visits,ym:s:users',
'dimensions': 'ym:s:TrafficSource',
'group' : 'day',
'filters' : "ym:s:isRobot=='No'",
'limit': 100
}
r = requests.get(API_URL, params = params, headers={'Authorization':API_token})Строка 3 — обращаемся к методу bytime.csv («.csv» — указание на то, что данные нам необходимы в табличном виде. Если вызывать метод bytime без «.csv», данные будут возвращены в формате JSON.)
Строка 12 — в параметры запроса добавили 'group' : 'day’ — указание на то, что данные необходимо сгруппировать по дням. Можно также группировать по часам, минутам, неделям, месяцам и проч. (Полный перечень возможных группировок и их обозначений смотрите в официальной документации «Яндекс.Метрики» по методу bytime).
Результат работы кода:
По сути мы получили сводную таблицу, в которой по столбцам указаны все значения из группировки «ym:s:TrafficSource» (источники трафика), в строках — значения за указанный диапазон дат.
Ограничения использования API-сервисов «Яндекс.Метрики»
Выше я писал о максимальном количестве метрик и группировок, которые можно использовать совместно в одном запросе.
Есть и другие важные ограничения (на момент написания материала):
Максимальное количество запросов с одного IP-адреса — не более 30 в секунду.
Из-под одной учетной записи (то есть с использованием одного токена) нельзя делать более 3-х параллельных запросов.
Максимальное количество обращений в сутки к одному счетчику — не более 5 000.
Актуальная информация об ограничениях — тут.
Что еще важно?
Отмечу, что у «Яндекс.Метрики» представлена очень подробная информация по работе с их API. Полная документация размещена по этому адресу.
Обращу внимание кратко на полезные (с моей точки зрения) разделы:
Виды отчетов (возвращаемых данных).
В статье я уделил внимание только сводным данным и в динамике. API «Яндекс.Метрики» может также возвращать данные в виде «Сравнение-таблица», «Drill Down», «Сравнение Drill Down».
Подробно о каждом методе написано в разделе «Виды отчетов» официальной документации.
Примечание — пусть и повторное, но важное: по умолчанию каждый метод возвращает данные в формате JSON, если необходимы данные в формате CSV, к имени метода необходимо добавлять символы «.csv».
Хорошо расписаны случаи вызова отдельных методов на реальных примерах.
Заключение
Надеюсь, эта статья окажется полезной для вас и вы сможете извлечь еще больше информации из статистики посещения сайта.
Подписывайтесь на обновления раздела нашей компании — в ближайшее время я напишу еще несколько материалов: продолжу делиться своим опытом digital-аналитики.