Учимся работать с API Яндекс.Метрики

Для извлечения статистических данных из Яндекс.Метрики необходимо воспользоваться специальным разделом API очётов. Сейчас актуальна версия v1. В качестве примеров, для получения статистики посещений всего сайта и конкретной страницы, мы выгрузим табличные данные в формате JSON, а затем преобразуем их и построим два линейных графика. Ниже привожу базовую структуру GET-запроса, с которым мы будем работать:

https://api-metrika.yandex.ru/stat/v1/data ? ids=<int>
                                           & oauth_token=<string>
                                           & metrics=<string>
                                           & dimensions=<string>
                                           & filters=<string>
                                           & date1=<string>
                                           & date2=<string>
                                           & sort=<string>

Яндекс.Метрика оперирует двумя базовыми сущностями: метрики (metrics) и группировки (dimensions). Метрики определяют числовые величины, которые могут быть рассчитаны на основе сессии или хита пользователя [количество посетителей, процент отказов, глубина просмотра, …]. Группировки предназначены для выборки данных по определённым признакам [страница входа, источник трафика, дата анализа, …].

Яндекс.Метрика работает отдельно с визитами (ym:s), где s — session, и хитами (ym:pv), где pv — pageview. В запросах к API эти характеристики нельзя использовать вместе в метриках и группировках. Список всех метрик и группировок можно посмотреть в документации.

Для детальных запросов существуют фильтры сегментации (filters). Они рассчитывают результат по отдельному сегменту данных. Например, когда нужно получить какие-либо данные только из поисковых систем или вытянуть статистику посещений по конкретной странице. С помощью параметров date1 и date2 можно задать отчётный период, а sort необходим для сортировки данных по признаку из dimensions. Небольшая шпаргалка ниже:

Параметр    Описание
——————————————————————————————————————————————————
ids         Номер счётчика.
oauth_token Токен авторизации.
metrics     Список метрик через запятую.
dimensions  Список группировок через запятую.
filters     Фильтры сегментации с условием.
date1       Дата начала периода выборки.
date2       Дата окончания периода выборки.
sort        Сортировка по метрикам и группировкам.

Для начала нужно зарегистрировать своё приложение на oauth.yandex.ru и получить oauth_token. В качестве ids выступает номер вашего счётчика (его можно узнать на главной странице Яндекс.Метрики). Параметры ids, oauth_token и metrics являются обязательными в простых запросах, но если применяется filters, то metrics и dimensions можно не указывать.

Предлагаю перейти в плоскость PHP и сформировать первый боевой запрос на примере моего блога, который получит количество визитов, просмотров и уникальных посетителей на всём сайте за последнюю неделю:

<?php

$url = 'https://api-metrika.yandex.ru/stat/v1/data';

$params = [
    'ids'         => '14446750',
    'oauth_token' => 'Z4AAAAAYZjVkAAQP-FYZ6SJdSkhesN0MJ0dXOZo',
    'metrics'     => 'ym:s:visits,ym:s:pageviews,ym:s:users',
    'dimensions'  => 'ym:s:date',
    'date1'       => '7daysAgo',
    'date2'       => 'yesterday',
    'sort'        => 'ym:s:date',
];

echo file_get_contents( $url . '?' . http_build_query($params) );

Как видите, в metrics и dimensions мы указали значения для визитов (ym:s). Это значит, что данные будут сформированы в рамках сессии по каждому пользователю. Если посетитель перезагрузит одну и туже страницу сто раз, то ym:s:pageviews не будет меняться. В случае работы с хитами (ym:pv), значение ym:pv:pageviews увеличилось бы на сто. Хиты собирают статистику в рамках каждого просмотра страницы.

Дату для отчётного периода можно указать в формате YYYY-MM-DD или её относительное значение: today, yesterday, 7daysAgo (номер дня можно заменить на свой). В результате Яндекс.Метрика вернула следующие данные в формате JSON:

{
  "query" : {
    "ids" : [ 14446750 ],
    "dimensions" : [ "ym:s:date" ],
    "metrics" : [ "ym:s:visits", "ym:s:pageviews", "ym:s:users" ],
    "sort" : [ "ym:s:date" ],
    "date1" : "2017-02-14",
    "date2" : "2017-02-20",
    "limit" : 100,
    "offset" : 1,
    "group" : "Week",
    "auto_group_size" : "1",
    "quantile" : "50",
    "attribution" : "Last",
    "currency" : "RUB"
  },
  "data" : [ {
    "dimensions" : [ {
      "name" : "2017-02-14"
    } ],
    "metrics" : [ 437.0, 800.0, 376.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-15"
    } ],
    "metrics" : [ 390.0, 559.0, 322.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-16"
    } ],
    "metrics" : [ 243.0, 370.0, 196.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-17"
    } ],
    "metrics" : [ 168.0, 274.0, 131.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-18"
    } ],
    "metrics" : [ 111.0, 145.0, 75.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-19"
    } ],
    "metrics" : [ 121.0, 150.0, 87.0 ]
  }, {
    "dimensions" : [ {
      "name" : "2017-02-20"
    } ],
    "metrics" : [ 132.0, 251.0, 103.0 ]
  } ],
  "total_rows" : 7,
  "total_rows_rounded" : false,
  "sampled" : false,
  "sample_share" : 1.0,
  "sample_size" : 1602,
  "sample_space" : 1602,
  "data_lag" : 74,
  "totals" : [ 1602.0, 2549.0, 988.0 ],
  "min" : [ 111.0, 145.0, 75.0 ],
  "max" : [ 437.0, 800.0, 376.0 ]
}

Секция query содержит параметры запроса, но нас больше интересует data, в которой содержатся наши статистические данные. Секция data представляет собой массив, где итеративно заполнены поля dimensions и metrics теми данными, которые были указаны в запросе. В нашем случае, поле dimensions содержит name — это название группировки ym:s:date. Поле metrics — массив с числовыми данными: ym:s:visits, ym:s:pageviews и ym:s:users.

Для обработки общих статистических данных можно использовать такие секции как: totals, min и max (в некоторых отчётах удобно анализировать сразу обобщённую информацию). Чтобы вывести данные из секции data на экран, скормим их Highcharts и построим линейный график:

Посмотреть процесс создания графика: PHP + Highcharts

Мы получили статистику по визитам, просмотрам и уникальным посетителям на всех страницах моего блога за последнюю неделю. Выглядит довольно таки неплохо. Для получения статистики конкретной страницы в Яндекс.Метрике нужно использовать filter. Вот так будет выглядеть запрос и построение графика на amCharts для просмотра главной страницы моего блога по хитам (ym:pv):

<?php

/////////////////////////////////////////////////////////
///// ПАРАМЕТРЫ GET-ЗАПРОСА ДЛЯ КОНКРЕТНОЙ СТРАНИЦЫ /////
/////////////////////////////////////////////////////////
$url = 'https://api-metrika.yandex.ru/stat/v1/data';

$params = [
    'ids'         => '14446750',
    'oauth_token' => 'Z4AAAAAYZjVkAAQP-FYZ6SJdSkhesN0MJ0dXOZo',
    'metrics'     => 'ym:pv:pageviews',
    'dimensions'  => 'ym:pv:date',
    'filters'     => rawurldecode("ym:pv:URL=='https://denisyuk.by/'"),
    'date1'       => '30daysAgo',
    'date2'       => 'yesterday',
    'sort'        => 'ym:pv:date',
];

/////////////////////////////////////////////////////////
///// ПОЛУЧИМ ДАННЫЕ В JSON И ПЕРЕВЕДЁМ ИХ В МАССИВ /////
/////////////////////////////////////////////////////////
$json = file_get_contents( $url . '?' . http_build_query($params) );
$data = json_decode($json, true)['data'];

/////////////////////////////////////////////////////////////
///// ПРЕОБРАЗУЕМ ДАННЫЕ ДЛЯ ЛИНЕЙНОГО ГРАФИКА AMCHARTS /////
/////////////////////////////////////////////////////////////
$tmpdata = [];

foreach ($data as $item) {
    $tmpdata[] = [
        'category' => $item['dimensions'][0]['name'],
        'column-1' => $item['metrics'][0],
    ];
}

////////////////////////////////////
///// ВЕРНЁМ JSON ДЛЯ AMCHARTS /////
////////////////////////////////////
$dataProvider = json_encode($tmpdata);

///////////////////////////////////////////////////////
///// ВЫВЕДЕМ HTML-КОД И ПОСТРОИМ ГРАФИК AMCHARTS /////
///////////////////////////////////////////////////////
echo <<<HTML
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://www.amcharts.com/lib/3/amcharts.js"></script>
  <script src="https://www.amcharts.com/lib/3/serial.js"></script>
  <script src="https://www.amcharts.com/lib/3/themes/patterns.js"></script>
  <script>
    AmCharts.makeChart("amcharts-container", {
      "type": "serial",
      "categoryField": "category",
      "startDuration": 1,
      "theme": "patterns",
      "categoryAxis": {
        "gridPosition": "start"
      },
      "graphs": [{
        "balloonText": "[[title]] за [[category]] — [[value]]",
        "bullet": "round",
        "title": "Просмотры",
        "id": "AmGraph-1",
        "type": "smoothedLine",
        "valueField": "column-1"
      }],
      "valueAxes": [{
        "title": "Количество"
      }],
      "titles": [{
        "text": "Просмотры https://denisyuk.by за последние 30 дней"
      }],
      "dataProvider": $dataProvider
    });
  </script>
</head>
<body>
  <div id="amcharts-container" style="max-width: 720px; height: 400px;"></div>
</body>
</html>
HTML;
//end

Обратите внимание, что значение filters мы обернули в функцию rawurldecode(). Это нужно делать, когда вы работаете со сложными фильтрами сегментации и кириллицей в запросах. Другие возможности фильтра доступны в документации: можно делать множественную выборку, использовать регулярные выражения, задействовать дополнительные операторы и др. В итоге мы получили график amCharts для статистики просмотров главной страницы по хитам:

Обновлено 23 Фев 2017: Решил добавить круговую диаграмму на Highcharts, чтобы разнообразить пост (под графиком сниппет кода для построения диаграммы). С помощью группировки ym:s:<attribution>TrafficSource и метрики ym:s:visits мы получили статистику по всем источникам трафика, а через фильтр сегментации, указав значение ym:s:visits>10, скрыли источники трафика меньше десяти, чтобы не портить график.

Посмотреть процесс создания круговой диаграммы: PHP + Highcharts

Мы рассмотрели базовые возможности API Яндекс.Метрики, которые могут пригодится для построения отчётов посещаемости своего сайта. Здесь важно понять, что все запросы формируются на основе metrics и dimensions, а через filters вычленяются конкретные данные по сайту. Если у вас остались вопросы, то задавайте их в комментариях, а я, по мере необходимости, буду редактировать или дополнять пост.

Продолжить обучение:

    Документация API очётов Яндекс.Метрики
    Становясь гуру API Яндекс.Метрики
    Получаем статистические данные, используя API Yandex Metrika
    Яндекс.Метрика для Laravel 5

Поделиться
Отправить
8 комментариев
seoonly.ru

Как всегда на высоте. Спасибо!

dj

Конгениально!

Roma

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

Вопрос же заключается в том — «Требуется одновременно на одну страницу выводить сразу несколько диаграмм (линейную, круговую и тд), при этом группировки и метрики, не перекликаются, для каждой диаграммы свой набор метрик и фильтров, возникла проблема, так как выводиться только последний вид диаграмм (по порядку), каким образом можно разрешить данную задачу?»

  • Спасибо.
Александр Денисюк

Я не вижу здесь проблемы, для каждого графика нужно запрашивать и строить данные по уникальному id, например, «graph-container-1». Обычный подход с инкапсуляцией. Создайте, например, для каждого графика отдельную функцию или класс. Если что, можете скинуть мне на почту исходники и описание как должно быть, я посмотрю.

Черноусов

Подскажите документацию для составления фильтров. Вот у вас написано
'filters' => rawurldecode(«ym:pv:URL=='https://denisyuk.by/'»),
Где посмотреть, как составлять?

Александр Денисюк

Условия фильтров нужно посылать в раскодированном виде, чтобы Я.Метрика нормально обработала запрос. Для PHP подойдёт rawurldecode(). Воспринимайте фильтры как if-конструкцию. Документация:

Фильтры с примерами
https://tech.yandex.ru/metrika/doc/api2/api_v1/segmentation-docpage/

Список группировок и метрик
https://tech.yandex.ru/metrika/doc/api2/api_v1/attrandmetr/dim_all-docpage/

Евгений

Подскажите пожалуйста как вывести самый первый график только по месяцам

Александр Денисюк

В dimensions и sort указываем ym:s:month, в date1 и date2 задаём свой диапазон.

Евгений

Спасибо за ответ, а как чтобы на графике выводились месяцы, а то просто циферки сейчас

Александр Денисюк

Можно сделать на PHP: перевести имя группировки в timestamp и извлечь название месяца.

Евгений

Я к сожалению не силен в PHP все делал по вашей инструкции, когда указываю ym:s:month, у меня просто выводятся цифры на графике 1,2,3...... , а надо как тут http://pr-cy.ru/advertising/ , буду очень благодарен за помощь.

Александр Денисюк
Вячеслав

Спасибо. Очень помогли

Популярное