Яндекс Метрика – популярный в среде маркетологов, арбитражников, разработчиков и владельцев сайтов сервис веб-аналитики. После установки Яндекс.Метрики пользователь начнет получать исчерпывающий набор статистических данных, позволяющих получить полное представление о посещаемости сайта.
Однако доступ к обычному веб-интерфейсу и отчетам Яндекс.Метрики имеет только владелец аккаунта, и он не предназначен для автоматического создания статистических отчетов. Эти недостатки функционала компенсируются с помощью API Яндекс.Метрики, которая позволяет необходимые аналитические данные получить программным способом. О том, как на практике использовать программный интерфейс Яндекс.Метрики и будет рассказано в этой статье.
Для чего служит API Яндекс.Метрики
API Яндекс.Метрики – мощный инструмент, позволяющий автоматизировать сбор статистических данных о посещаемости сайта. Программное управление счетчиками, показ статистики посещаемости в реальном времени, автоматическое формирование отчетов с заданными параметрами, упрощение доступа к статистике сайта сотрудникам компании и возможным рекламодателям – вот неполный перечень возможностей программного интерфейса Яндекс.Метрики.
Естественно, чтобы научиться работать с API Яндекс.Метрикой, необходимо уметь программировать на таких языках, как PHP, Java или Python. Однако, поскольку API Яндекс.Метрики интегрирован в различные веб-платформы, в принципе работать с ним могут даже вебмастера, не имеющие или имеющие минимальные навыки программирования. Например, чтобы на сайте, работающем под управлением какой-либо популярной CMS (Drupal, Joomla, WordPress и т.д.) создать страницу, отображающей статистику посещаемости в реальном времени, вебмастеру достаточно установить и настроить соответствующий модуль. Полный список всех веб-платформ, в которые интегрирован API Яндекс.Метрики, вы можете найти здесь.
Виды API Яндекс.Метрики
API Яндекс.Метрики состоит из четырех независимых друг от друга программных интерфейсов – API управления, API отчетов, API совместимый с Google Analytics Core Reporting API и Logs API.
API управления
API управления Яндекс.Метрики позволяет автоматизировать работу со счетчиками Яндекса. С помощью API управления можно программными методами создавать новые и удалять старые счетчики, изменять их настройки, управлять целями, фильтрами и прочими объектами, менять права доступа и т.д.
API отчетов
API отчетов позволяет программными методами получать весь набор статистических данных, предоставляемых Яндекс.Метрикой. Чтобы получить статистический отчет, необходимо сформировать запрос на получение уже обработанных и систематизированных статистических данных, которые называются группировками и метриками. Подробнее о группировках и метриках будет рассказано далее.
API, совместимый с Google Analytics Core Reporting API
Для тех, кому ранее приходилось работать с API Google Analytics Core Reporting этот раздел API Яндекс.Метрики покажется самым удобным, поскольку при формировании запросов используются те же самые названия параметров. Однако по сравнению с API Google Analytics Core Reporting функционал API Яндекс.Метрики ограничен. Текущая (на начало 2022 г.) реализация API Яндекс.Метрики совместима с третьей версией API Google Analytics.
Logs API – работа с неагрегированными данными
Как было указано выше, API отчетов позволяет получить статистические данные, уже обработанные и представленные в виде группировок и метрик. Logs API дает возможность получить доступ к необработанным, «сырым» статистическим данным, из которых программист может самостоятельно сформировать статистический отчет, обрабатывая и анализируя исходные данные.
Ограничения и недостатки API Яндекс.Метрики
API Яндекс.Метрики в целом совершенный и удобный инструмент автоматизации получения статистических отчетов, но, как и любой веб-сервис, он имеет свои недостатки и ограничения:
- авторизационный OAuth-токен, который необходим для работы с API Яндекс.Метрики (см. следующий параграф) привязан к аккаунту на Яндексе. В случае возникновения любых проблем с аккаунтом (взлом, сброс паролей, передача прав) все OAuth-токены, ассоциированные с этим аккаунтом немедленно аннулируются, восстановить скомпрометированный токен или автоматически получить новый невозможно;
- чтобы полностью освоить API Яндекс.Метрики, необходимо иметь некоторые навыки программирования;
- функционал API Яндекс.Метрики, совместимый с Google Analytics Core Reporting API сильно ограничен по сравнению с оригиналом и, по отзывам пользователей, содержит баги;
- некоторые возможности API Яндекс.Метрики плохо документированы;
- количество запросов от одного пользователя ограничено 5-тью тысячами в сутки, также с одного IP-адреса за одну секунду допускается делать максимум 30 запросов.
Начало работы с API Яндекс.Метрика
Чтобы начать работу с API Яндекс.Метрики, необходимо зарегистрировать приложение и получить авторизационный OAuth-токен (его еще называют отладочный OAuth-токен). Для этого перейдите на главную страницу API Яндекс.Метрики – https://yandex.ru/dev/metrika/ и щелкните по кнопке «Получить OAuth-токен»:
На странице https://oauth.yandex.ru/client/new/ задайте название вашего приложения, а также, по желанию, дайте его краткое описание и загрузите иконку (описание и иконка могут быть полезными, если вы собираетесь использовать другие сервисы Яндекса и создавать новые приложения):
Прокрутите страницу вниз для перехода в раздел Платформы. Выберите опцию «Веб-сервисы» и щелкните по полю «Подставить URL для разработки» для определения Callback URL:
Далее в разделе «Доступы*» найдите секцию Яндекс.Метрика. Отметьте флажком чекбокс «Получение статистики, чтение параметров своих и доверенных счётчиков»:
Прокрутите страницу до конца и щелкните по кнопке «Создать приложение»:
После этого будет создано новое приложение Яндекс, и вы получите его идентификатор и пароль:
Как идентификатор, так и пароль представляют собой последовательность из 32 букв и цифр. Вот так примерно могут выглядеть идентификатор и пароль зарегистрированного приложения Яндекс:
ID: 1de44f65f12527e866fe45c0ac24f486
Пароль: 4824afc14f683b9kd77fd475c5g79e1u
Скопируйте и сохраните в надежном месте идентификатор и пароль вашего приложения. Чтобы изменить параметры созданного приложения щелкните по кнопке «Редактировать» – так вы сможете расширять доступы, менять пароль и т.д.
Получение отладочного OAuth-токена
Чтобы получить авторизационный (отладочный) OAuth-токен, перейдите по следующей ссылке (вы должны быть авторизованы в системе Yandex):
https://oauth.yandex.ru/authorize?response_type=token&client_id=<ID_вашего_приложения>
То есть, если идентификатор вашего приложения такой, как показанный выше (1de44f65f12527e866fe45c0ac24f486), то ссылка будет выглядеть так:
https://oauth.yandex.ru/authorize?response_type=token&client_id=1de44f65f12527e866fe45c0ac24f486
После перехода по вышеописанной ссылке вы окажетесь на странице https://oauth.yandex.ru/verification_code#access_token=<ваш_отладочный_токен>&token_type=bearer&expires_in=31536000
Отладочный OAuth-токен – это последовательность из 39 знаков, он выглядит примерно так:
AQAAAAAISvplAAX36u8Ulq5bkUCCkjYcGZVf2hY
Время жизни отладочного OAuth-токена составляет 365 дней. Скопируйте и сохраните свой отладочный токен. После получения OAuth-токена можно приступить к непосредственной работе с API Яндекс Метрики, но сначала давайте разберемся в используемых форматах и терминологии.
Коротко о визитах, хитах, целях и уникальных посетителях
Чтобы научиться работать с отчетами Яндекс.Метрики, необходимо хорошо понимать смысл используемых терминов. Центральное место в принятой терминологии занимают визиты, хиты, цели и пользователи (уникальные посетители).
Пользователем или уникальным посетителем называется посетитель, зашедший на сайт с одного и того же браузера за определенный период времени, например за сутки. Уникальность определяется по файлу cookie, сохраненному на устройстве пользователя.
Визит – это совокупность всех действий, совершенных пользователем на сайте за выбранный период времени. Иногда визит называют сеансом или сессией.
Хит – любое значимое действие, совершенное пользователем на сайте. Хитом может считаться, например:
- щелчок по кнопке отправки формы;
- переход по любой ссылке, например, в результате щелчка по рекламному баннеру или переход на другую страницу сайта;
- просмотр видео;
- скачивание файла со страницы сайта;
- само по себе посещение страницы сайта также считается хитом.
Цель (goal) – определенное действие, совершенное пользователем, которое владелец сайта считает для себя значимым. Целью может быть, например, заполнение и отправка формы, просмотр видео, щелчок по рекламной ссылке или баннеру, покупка рекламируемого товара и т.д. Вот тут подробный гайд по настройке целей.
Группировки и метрики
Метрики и группировки – важнейшие понятия API Яндекс Метрики:
- метрики – числовые статистические данные, характеризующие посещаемость сайта. Примеры: ym:s:visits – общее количество визитов за выбранный период времени, ym:s:visitsPerDay – число визитов за один день, ym:s:pageviews – общее количество просмотренных посетителями сайта страниц за выбранный период времени, ym:s:users – общее количество пользователей (уникальных посетителей) за выбранный период и т.д.;
- группировки – это критерии, на основании которых полученные статистические данные соединяются (группируются) в таблицы. Чтобы лучше уяснить смысл этого термина, возьмите на заметку, что в английской версии API Яндекс.Метрики для обозначения группировок используется слово dimensions – величины, измерения, размерности. Примеры: пусть известно общее количество уникальных посетителей сайта за определенный период времени (это метрика ym:s:users), тогда группировка ym:s:browser будет представлять собой таблицу, в которой общее число посетителей разбивается по строкам в соответствии с используемыми ими браузерами. Точно так же группировка ym:s:operatingSystem образует таблицу, в которой посетители распределяются в соответствии с операционными системами их устройств.
Полный список группировок и метрик с их описанием можно найти в документации Яндекс.Метрики на этой странице.
Пара слов о форматах JSON и CSV
Как уже указывалось выше, запросы к API Яндекс.Метрика возвращаются в виде отчетов в формате JSON или CSV (по выбору пользователя, нужный формат указывается в запросе). Формат JSON является форматом, используемым по умолчанию. Запросы к Яндекс Метрике также формируются на основе формата JSON.
Формат JSON изначально был разработан для языка JavaScript (аббревиатура JSON расшифровывается как JavaScript Object Notation), чтобы заменить формат XML, который слишком громоздок для работы с простыми данными. Данные в JSON кодируются в виде пар ключ – значение и легко преобразуются в массивы и объекты JavaScript и наоборот. Формат JSON быстро завоевал заслуженное признание в среде разработчиков и сейчас во всех популярных языках программирования существуют библиотеки для работы с этим форматом.
Пример данных в формате JSON: { "key1": "value1","key2": "value2","key3": "value3"}
Пример преобразования строки формата JSON в массив на языке PHP:
$strJason = '{"key1":"value1","key2":"value2","key3":"value3"}';
$arrayPHP = json_decode($strJason, true);
print_r($arrayPHP);
Результат работы программы: Array ( [key1] => value1 [key2] => value2 [key3] => value3 )
Функция json_decode($strJason, true) с дополнительным параметром true преобразует JSON строку в ассоциативный массив PHP. Если выполнить функцию без этого дополнительного параметра (в нашем случае json_decode($strJason);), то JSON строка будет преобразована в PHP объект.
Обратный пример – преобразование ассоциативного массива PHP в строку JSON:
$arrayPHP = array(
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
);
$strJason = json_encode($arrayPHP);
echo $strJason;
Результат работы программы: {"key1":"value1","key2":"value2","key3":"value3"}
Формат CSV – простейший формат, позволяющий преобразовать текстовые данные в таблицы. Пример исходного текста формата CSV (в нем в качестве разделителей приняты запятые):
Государство, Площадь тыс. кв. км., Столица
Великобритания, 244, Лондон
Германия, 357, Берлин
Франция, 551, Париж
Из этого текста получается такая таблица:
| Государство | Площадь, тыс. кв. км. | Столица |
| Великобритания | 244 | Лондон |
| Германия | 357 | Берлин |
| Франция | 551 | Париж |
Если в качестве разделителей выбрать знак «точка с запятой» («;») как здесь:
Государство; Площадь тыс. кв. км.; Столица
Великобритания; 244; Лондон
Германия; 357; Берлин
Франция; 551; Париж
Во многих языках программирования имеются встроенные функции для работы с файлами формата CSV. Например, в PHP имеется функция fgetcsv(), которая читает строки из CSV-файла, производит разбор, и возвращает найденные поля в виде списка.
Отметим также, что на основе данных в форматах JSON и CSV можно не только формировать простые таблицы, но и создавать сложные графики и схемы, используя различные популярные инструменты визуализации, такие как D3.js, Google Charts, Chart.js и др.
Работа с API Яндекс.Метрика – простые примеры
Итак, вы получили OAuth-токен и имеете счетчик Яндекс Метрики. Напишем простой скрипт на языке PHP, иллюстрирующий работу с API Яндекс.Метрика, в данном случае с API отчетов. Общий алгоритм работы с API отчетов такой:
- сформировать запрос к серверу Яндекса на получение выбранных статистических данных в избранном формате;
- полученный ответ сохранить на своем сервере в виде текстового файла с произвольным расширением;
- открыть сохраненный файл и произвести разбор для извлечения статистических данных;
- вывести или визуализировать полученные данные в виде таблиц или графиков.
Заметьте, что пункты 2 и 3 не обязательны – вы можете получить, обработать и вывести в браузере полученные от Яндекса статистические данные без сохранения. Однако, как было указано выше, Яндекс ограничивает количество запросов от одного аккаунта. Поэтому, если, например, запрос на получение статистики с сервера Яндекса начнут делать сотрудники крупной компании, лимиты на количество запросов будут быстро исчерпаны. Именно поэтому выгодней сохранить результаты запроса на собственном сервере и уже к ним обеспечить доступ сотрудникам компании.
Запросы к серверу проще всего формировать с помощью CURL. Библиотеки и расширения CURL существуют для всех популярных языков программирования.
Пример: файл ymetr.php – получение избранных метрик
<?php
// $your_OAuth_token - ваш авторизационный токен
$your_OAuth_token = 'AQAAAAAISvplAAX36u8Ulq5bkUCCkjYcGZVf2hY';
// $counter_ID - номер счетчика, для которого вы запрашиваете статистику
$counter_ID = '12345678';
//$list_of_metrics - список метрик, по которым запрашивается статистика
// ym:s:users - число уникальных посетителей за отчетный период
// ym:s:visits - количество визитов
// ym:s:pageviews - количество просмотренных страниц
// ym:s:pageDepth – глубина просмотра
// ym:s:avgVisitDurationSeconds – среднее время визита в минутах и секундах
$list_of_metrics='ym:s:users,ym:s:visits,ym:s:pageviews,ym:s:pageDepth,ym:s:avgVisitDurationSeconds';
$parametrs = array(
=> $counter_ID,
'metrics' => $list_of_metrics,
'date1' => 'yesterday', // началоотчетногопериода
'date2' => 'today', //конец отчетного периода
//Раскомментируйте, если хотите получить статистику для определенной страницы
// 'filters' => "ym:pv:URL=='https://somesite.com/somedir/somepage.html '",
'pretty' => 'true' //задано «удобочитаемое» форматирование вывода
);
// Формируем запрос. Запросы идут только по безопасному протоколу HTTPS
$curl_desc = curl_init('https://api-metrika.yandex.net/stat/v1/data/bytime?' . urldecode(http_build_query($parametrs)));
curl_setopt($curl_desc, CURLOPT_HTTPHEADER, array('Authorization: OAuth ' . $your_OAuth_token));
curl_setopt($curl_desc, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_desc, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl_desc, CURLOPT_HEADER, false);
// $result - результат выполнения запроса - данные в формате JSON
// если запрос не прошел $result получит значение false
$result = curl_exec($curl_desc);
curl_close($curl_desc);
if($result) // если данные получены
{
//Создаем директорию, если ее не существует
$dirname = $_SERVER['DOCUMENT_ROOT'] . '/ymetric_reports';
if(!file_exists($dirname))
mkdir($dirname, 0777);
$current_time = date("d-m-y_G-i-s");
file_put_contents($dirname ."/report_". $current_time . ".json", $result);
}
?>
После копирования кода, прежде всего, введите настоящие значения для переменных $your_OAuth_token и $counter_ID (то есть замените на ваш отладочный OAuth токен и действительный номер Яндекс счетчика). Затем обратите внимание на поля date1 и date2 – начало и конец отчетного периода. Их можно вводить в формате ГГГГ-ММ-ДД, например 2022-01-25 (25 января 2022 года) или использовать условные значения today – сегодня, yesterday – вчера, NdaysAgo – N дней назад, то есть 5daysAgo – 5 дней назад, 100daysAgo – 100 дней назад и т.д. Для остальных полей оставлены значения по умолчанию.
Eсли необходимо получить статистику не для всего сайта, а для отдельной страницы, адрес которой http://somesite.com/somedir/somepage.html, то полю filters надо задать значение "ym:pv:URL=='https://somesite.com/somedir/somepage.html '".
Подробнее о значениях полей запроса вы можете прочитать здесь.
Скопируйте и сохраните код в файл ymetr.php. Файл ymetr.php в свою очередь сохраните в любой подходящей директории на вашем сервере.
Программа выполняет следующую работу:
- формирует и производит запрос к серверу api-metrika.yandex.net (запрашиваются 4 метрики ym:s:users, ym:s:visits, ym:s:pageviews, ym:ad:clicks);
- если результат запроса успешен, полученные статистические данные записываются в файл отчета с расширением *.json
Файл отчета имеет название report_<дата>_<время>.json, где <дата> и <время> соответствуют дате и времени записи файла. Например, report_25-01-22_14-12-21.json – файл создан 25 января 2022 года в 14 часов 12 минут 21 секунду. Файл записывается в папку ymetric_reports, которая создается в той же директории, в которую помещен файл ymetr.php.
Настройте планировщик задач на вашем севере, который бы запускал файл ymetr.php, каждые 20-30 минут (если у вас сайт с высокой посещаемостью, то ymetr.php можно запускать еще чаще, например раз в минуту). После каждого запуска программы будет создаваться новый файл отчета.
Файл read_metr.php – простейший пример извлечения метрик из полученных данных
После того, как данные были получены и сохранены на сервере в файле отчета (в нашем случае в файле report_25-01-22_14-12-21.json), его необходимо открыть и декодировать. Именно это и делает следующий код:
<?php
//header здесь только для того, чтобы русский шрифт выводился нормально
header('Content-type: text/html; charset=windows-1251');
$file_path = 'ymetric_reports/report_25-01-22_14-12-21.json';
$json_text = file_get_contents($file_path);
$json_array = json_decode($json_text, true);
//print_r($json_array['totals']);
?>
Уникальных посетителей:
<?php echo $json_array['totals'][0][0];?>
<br>
Визитов:
<?php echo $json_array['totals'][1][0];?>
<br>
Просмотренных страниц:
<?php echo $json_array['totals'][2][0];?>
<br>
Глубина просмотра:
<?php echo $json_array['totals'][3][0];?>
<br>
Среднее время визита:
<?php echo $json_array['totals'][4][0];?>
Скопируйте код в файл read_metr.php, который поместите в ту же директорию, что и файл ymetr.php. Теперь read_metr.php можно открыть браузером.
FAQ
