Datalytics

Tiger got to hunt, Bird got to fly, Man got to sit and wonder, «Why, why, why?»

Новые пользовательские группировки в API Яндекс.Метрики

1 июня 2016, 17:28

30 мая 2016 года Яндекс.Метрика выкатила новый тип сегментации: сегментацию по пользователям. Теперь аналитика в Метрике стала человекоцентрированной (вернее пользователецентрированной), а интерфейс сегментации значительно упростился. С внедрением сегментации по пользователям в API Метрики появились новые группировки и метрики. Пока что они не документированы, но, надеюсь, в скором времени описание новых возможностей появится в документации API Яндекс.Метрики.

Одна из самых интересных новых группировок — ym:s:specialUser. При добавлении этой группировки в dimensions мы сможем детализировать данные по пользователям. Например, можно получить отчет по поисковым системам, с помощью которого будет видно пользователей, приходивших на сайт несколько раз, но по разным запросам или поисковым системам. Запрос выглядит так:

(Вместо «token» вставить авторизационный OAuth-токен, вместо «id» — номер счетчика. Чтобы получить данные в CSV нужно добавить .csv после data в запросе. Подробнее о работе с API Яндекс.Метрики можно прочитать в моей статье)

Вот как выглядит такой отчет в Excel:

На отчете видно, что один и тот же пользователь посещал сайт несколько раз с 26 по 31 мая, при этом каждый визит был зафиксирован с разных поисковых фраз.
Использование группировки ym:s:specialUser — это интересная возможность, позволяющая выявить ассоциированные запросы, или построить отчет схожий с многоканальными последовательностями (MCF) в Google Analytics.

Еще один запрос, в котором можно использовать ID пользователя — получение данных о кампаниях и ключевых фразах Яндекс.Директа:

Получившийся отчет выглядит так:

С помощью этих данных мы можем понять сколько пользователей заходят с двух или более кампаний Яндекс.Директа (определить % пересечения аудитории между кампаниями). Также эти данные позволяют нам понять какие пользователи совершают посещения, перейдя с разных запросов Яндекс.Директа.

Еще одно нововведение: появились новые типы группировок и метрик. Раньше в Метрике было два типа группировок и метрики: уровня хита (они начинались с ym:pv) и уровня визита (они начинались с ym:s), теперь появился уровень пользователя. Группировки и метрики этого типа начинаются с ym:u. Именно по этим группировкам производится сегментация пользователей.

Одна из самых полезных группировок пользовательского типа — ym:u:userFirstVisitDate. Эта группировка содержит в себе дату первого визита пользователя. Её удобно использовать в filters для того, чтобы получить данные о посещениях пользователей с конкретной датой первого визита. Пример запроса:

Обратите внимание, что при фильтрации используется специальный оператор EXIST.

Такой отчет будет содержать данные только тех пользователей, которые совершили первое посещение сайта в определенную дату (в моем примере — 13 мая 2015):

Приведу еще пару интересных примеров использования группировок ym:u.

Во-первых, мы можем получить данные обо всех пользователях:

Такой запрос к API возвратит отчет по всем пользователям, которые были на сайте в отчетный период, с указанием различных параметров (например, пол):

Обратите внимание, содержимое параметра ym:u:userID совпадает с ym:s:specialUser. Это означает, что мы можем сопоставить данные из любого отчета, в котором используется ym:s:specialUser, с данными пользователей, например, с датой первого визита. Это открывает возможности для проведения когортного анализа в Яндекс.Метрике.
Еще один важный момент: в запросе нельзя использовать dimensions разных типов, то есть мы не можем в одном запросе получить группировки с ym:u и ym:s одновременно, например, ym:u:userID и ym:s:date. Поэтому придется делать два запроса и по ym:u:userID джоинить данные между собой.

Во-вторых, с помощью filters мы можем получать данные о специфичных пользователях, выполнивших какое-либо условие. К примеру, вот запрос, позволяющий получить пользователей, которые хотя бы раз заходили с источника трафика Google:

Напоследок, привожу полный список новых группировок, которые мне удалось раскопать:

  • ym:s:specialUser — Идентификатор посетителя (uid) уровня визита
  • ym:u:userID — Идентификатор посетителя (uid) уровня посетителя
  • ym:u:userVisits — Общее число визитов посетителя
  • ym:u:totalVisitsDuration — Суммарная длительность визитов посетителя
  • ym:u:pageviews — Суммарное количество просмотров страниц пользователем
  • ym:u:userFirstVisitDate — Дата первого визита посетителя
  • ym:u:firstSourceEngine — Первый источник трафика (детально) посетителя
  • ym:u:firstTrafficSource — Тип первого источника трафика посетителя
  • ym:u:gender — Пол посетителя
  • ym:u:ageInterval — Возрастной диапазон посетителя
  • ym:u:interest — Интерес пользователя
  • ym:u:daysSinceFirstVisitOneBased — Количество дней с первого визита пользователя

Список полезностей

4 октября 2015, 23:34

Как читать свои сообщения ВКонтакте через API

28 сентября 2015, 23:13

Я любитель использовать API для «общения» с повседневными сервисами. Например, моя статья о API Яндекс.Метрики как раз об этом: как без интерфейса получать нужные данные. Не так давно меня посетила мысль использовать API ВКонтакте, вместо привычного интерфейса. Зачем это может быть нужно? Например, чтобы прочитать свои сообщения, при этом не заходя на страницы vk.com, а значит не появляясь онлайн. У меня вот есть социофобская черта — я не люблю появляться Вконтакте онлайн, но иногда туда приходят сообщения, и было бы неплохо иметь возможность эти сообщения читать, при этом онлайн не появляясь.

Получить доступ к API для доступа к пользовательским данным можно в 3 шага:

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

Первый и второй шаг нужно сделать 1 раз, а третий шаг придется выполнять каждый раз, когда захочется прочитать свои сообщения ВКонтакте.

Итак, первый шаг: создание своего приложения для API Вконтакте.

1 . Заходим на страницу http://vk.com/dev
2 . Выбираем «Создать приложение»

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

4 . Потом нужно подтвердить приложение с помощью СМС-кода, отправленного на телефонный номер
5 . Приложение создано и нас встречает страница с информацией о нашем приложении

6 . Переходим на страницу «Настройки» и в поле «Состояние» выбираем «Приложение включено и видно всем»

7 . Нажимаем «Сохранить изменения»
8 . Также на этой странице нам пригодятся ID приложения (в красной рамке на изображении ниже) и защищенный ключ (и в синей рамке на изображении ниже)

Второй шаг: получение токена для доступа к данным
Этот шаг надо делать будучи залогиненным Вконтакте под тем пользователем, к данным которого нужно получить доступ.
1 . Делаем в браузере запрос https://oauth.vk.com/authorize?client_id=5086933&display=page&redirect_uri=https://oauth.vk.com/blank.html&display=page&scope=messages,offline&response_type=code&v=5.37, где client_id — это ID нашего приложения со страницы настроек. В параметре «scope» перечисляются права доступа нашего приложения. В нашем случае, «messages» означает, что приложение будет иметь доступ к чтению сообщений пользователя. Разрешение «offline» дает нашему приложению доступ к данным пользователя в любое время, при этом доступ будет бессрочный. Помимо «messages» можно задать другие разрешения, которые надо также перечислять через запятую. Например, разрешение «friends» дает доступ к друзьям, тогда scope=messages,friends,offline. Про все возможные разрешения написано тут.
2 . Мы окажемся на странице, где должны разрешить созданному приложению доступ к аккаунту:

3 . Нажимаем «Разрешить»
4 . После этого нас перебросить на страницу вида https://oauth.vk.com/blank.html#code=ce72f6a9157bef81f6, где параметр code содержит верификационный код, действительный 1 час с момента его получения. Копируем этот код
5 . Делаем в браузере запрос https://oauth.vk.com/access_token?client_id=5086933&client_secret=kQwYLYh12Ar21eJzH3R7&redirect_uri=https://oauth.vk.com/blank.html&code=ce72f6a9157bef81f6, где client_id — ID приложения со страницы настроек, client_sercet — защищенный ключ (также со страницы настроек приложения), а code — верификационный код, который мы получили в предыдущем пункте

6 . На открывшейся странице будет в формате JSON представлен токен для доступа в значении ключа access_token:

P.S.: Чтобы JSON смотрелся в браузере также хорошо («pretty») как у меня на скриншоте надо установить какое-нибудь разрешение для браузера, позволяющее
Помимо кода доступа JSON содержит ключ expires_in, содержащий срок действия токена (у нас там 0, т. к. токен бессрочный) и user_id пользователя, доступ к данным которого возможен с помощью полученного токена. Копируем токен, он нам теперь будет нужен каждый раз, когда мы будем делать запрос к API.

Третий и последний шаг: получение списка входящих сообщений
Перечень всех методов для работы с API Вконтакте доступен по ссылке, но нам пока пригодится только метод messages.get, с помощью которого можно получить список входящих или исходящих сообщений. Вполне возможно, что захочется еще и отправлять сообщения, тут нужен метод messages.send.

Использовать метод messages.get предельно просто:
Просто делаем запрос вида https://api.vk.com/method/messages.get?access_token=f73dc057f8d81d96, где access_token — токен для доступа, который мы получили на втором шаге. Получаем приблизительно такую картину:

Каждый объект в массиве response — это отдельное сообщение, body — это текст сообщения, uid — идентификатор пользователя, отправившего сообщение, read_state — прочитано ли сообщение (1) или не прочитано (0), out — входящее сообщение (0) или исходящее (1), date — дата сообщения в формате posix, mid — идентификатор сообщения.

Чтобы получить исходящие сообщения к запросу надо добавить параметр out=1:
https://api.vk.com/method/messages.get?access_token=f73dc057f8d81d96&out=1

Вот такой нетривиальный способ читать свои сообщения Вконтакте.

Становясь гуру API Яндекс.Метрики

1 сентября 2015, 0:12

To-do: Надо что-то сделать с пафосным названием статьи

1. Лирическое отступление

Давно вынашивал идею написать что-то основательное про API Метрики. Взяться за дело меня вдохновила эта статья на хабре, посвященная выгрузке данных с помощью API Яндекс.Метрики. Но в ней, на мой взгляд, все сложновато, зачем создавать инстансы в Amazon, чтобы писать Python-скрипты? Достаточно поставить IPython и будет интерактивное счастье прямо в браузере, с блэкджеком и скаттер-плотами (для тех кто понимает о чем я). Но о том как использовать API Метрики с помощью IPython я напишу когда-нибудь потом, а в этой статье я хотел бы рассказать о том как можно получать данные Метрики в формате CSV с помощью одного запроса через браузер. Один CTRL+C, один CTRL+V, потом Enter и никакой интерфейс Метрики больше не нужен.

Просто перейдя по ссылке можно выгрузить нужные данные:
https://api-metrika.yandex.ru/stat/v1/data.csv?metrics=ym:s:visits,ym:s:pageviews&dimensions=ym:s:lastTrafficSource&date1=31daysAgo&date2=yesterday&limit=10000&offset=1&ids=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Но для начала надо научиться эту ссылку формировать.

С функционалом API Яндекс.Метрики я знаком достаточно давно — с момента выхода второй версии API, которая состоялась одновременно с выходом Метрики 2.0. До этого времени работал только с Google Analytics, так как Яндекс.Метрика в принципе не устраивала своим скудным на тот момент функционалом: я осознавал систему как счетчик веб-статистики, но проделать серьезную аналитическую работу в ней было сложно, разве что с помощью «Конструктора отчетов». Что я подразумеваю под «серьезной» аналитикой? Прежде всего, в моем понимании это построение отчетов с множеством параметров и показателей, а также возможность сегментировать данные по различным критериям. Гигантская проблема заключалась в том, что методы «Констуктора отчетов» не были доступны в первой версии API Метрики, а значит чтобы автоматизировать сбор нужных данных приходилось парсить веб-страницы Метрики, что, мягко говоря, не удобно. Выход нового API стал для компании, в которой я работаю, мощным толчком перейти с использования Google Analytics на Яндекс.Метрику в качестве основной системы веб-аналитики. Причин тут много:

  • Широкая распространенность счетчиков Метрики в рунете
  • Метрика продолжает показывать поисковые запросы, в отличие от Google Analytics
  • Подробная статистика по кампаниям Яндекс.Директа с детализацией до поисковых запросов
  • Как позже оказалось: дружелюбная и достаточно быстрая поддержка (которой я уже, наверно, надоел, но они продолжают героически отвечать)

Миграция с API GA на API Метрики оказалась весьма безболезненной, во многом благодаря тому, что разработчики обеспечили совместимость запросов к Google Analytics Core Reporting API, сделав отдельное совеместимое API. С Core Reporting я был «на ты», поэтому начать пользоваться совместимым API было проще простого.

Если кому интересно про работу с Google Analytics Core Reporting API, то можете ознакомиться с презентацией моего доклада на iMetrics. Чтобы окончательно добить эту тему, по мотивам доклада написал две статьи: первая и вторая. С тех пор интерфейс GA Query Explorer несколько изменился, но изменения больше косметические. Вообще, благодаря Query Explorer работать с API Google Analytics легко. Такого инструмента мне не хватает в Яндекс.Метрике.

Позже оказалось, что совместимое API не содержит всех доступных в Метрике параметров, к тому же в нем периодически попадались неприятные баги, поэтому было решено переходить на использование нативного API Яндекс.Метрики 2.0.

2. Группировки и метрики

Яндекс.Метрика (и её API) оперирует двумя основными сущностями: Dimensions (группировки) и Metrics (метрики). Эта терминология пришла из технологии обработки данных OLAP, она также встречается и в Google Analytics. Благодаря этому, API GA и API Метрики 2.0 очень похожи, и это существенный плюс, потому что начать работать с нативным API Метрики было очень легко, имея опыт работы с API GA.

Группировки/Dimensions (мне их привычнее называть «измерениями», но буду придерживаться терминологии Метрики) — это какой-либо атрибут визита или хита. Как ясно из названия, группировки позволяют группировать данные по определенным признакам.

Примеры группировок: Источник трафик, Город, Браузер, Страница входа.

Группировки — это все те параметры, которые можно найти в одноименном разделе при построении отчета в интерфейсе Метрики:

Метрики/Metrics — это числовые величины, которые связаны с визитом или хитом.

Примеры метрик: количество визитов, показатель отказов, среднее время на сайте.

В интерфейсе метрики представлены в правой части табличных отчетов и их также список также можно настраивать:

3. Пример

Метрики и группировки взаимосвязаны. Чтобы понять эту взаимосвязь можно рассмотреть пример посетителя, совершающего посещение сайта.

Пускай, это единственное посещение за всю историю сайта. Атрибуты посетителя, например, его город, браузер, источник трафик, пол, возвраст, все что удалось определить Яндекс.Метрике — это группировки. Яндекс.Метрика определила, что пользователь: пришел из Москвы, из поисковой системы Яндекс.

  • Значение группировки «Город» для этого посещения будет «Москва»
  • Значение группировки «Источник трафика» — «Переходы из поисковых систем»

В ходе посещения посетитель просматривает 5 страниц в течение 4 минут 40 секунд, тогда:

  • Значение метрики «Просмотры» будет равно 5 страницам
  • Значение метрики «Длительность визита» — 280 секунд
  • Значение метрики «Отказы» будет равно 0%, т. к.
    доля отказов для этого посещения будет равна 0%, т. к. пользователь просмотрел более одной страницы. Общая статистика посещений будет выглядеть так:

Общая статистика — это отчет, в котором отсутствуют группировки. Создав отчет с группировкой «Город» и метриками «Визиты» и «Просмотры» мы получим вот такой отчет:

Добавим группировку «Источник трафика» и отчет станет выглядеть вот так:

А теперь предположим, что пришел второй посетитель, тоже через ПС Яндекс, но из Петербурга. Он просмотрел за свой визит 1 страницу и был на сайте меньше 15 секунд. Такой визит будет считаться отказным, значит:

  • Значение метрики «Просмотры» будет равно 1 странице
  • Значение метрики «Длительность визита» — 0 секунд
  • Значение метрики «Отказы» — 100%

Общая статистика посещений станет такой:

Если мы построим отчет с единственной группировкой «Источник трафика», то отчет будет иметь такие же значения метрик, как и в целом по сайту, т. к. у нас два посетителя, у которых одинаковое значение группировки «Источник трафика» — они оба пришли из поисковых систем, данные по ним сгруппировались:

Теперь изменим группировку отчета на «Город»:

Отчет принимает совершенно другой вид: у нас в нем появились две строки, несущие в себе два диаметрально противополжных факта. Отсюда вывод: правильные группировки помогают увидеть правильную информацию в правильном разрезе. Я считаю это основопологающим принципом веб-аналитики и аналитики данных вообще.

Надеюсь, этот пример дал понимание что такое группировки и метрики.

4. Получение доступа к API

Метрика использует протокол OAuth. Этот протокол позволяет работать с данными Яндекса от лица пользователя Яндекса через приложение, зарегистрированное на Яндексе. Приложение получает доступ к данным пользователя с помощью специального ключа, называемого токеном. Итак, прежде чем начать использовать API Яндекс.Метрики нам нужно создать приложение и получить от имени пользователя OAuth-токен, с помощью которого мы будем делать свои запросы к API.

1: Заходим на страницу https://oauth.yandex.ru/
2: Нажимаем «Зарегистрировать новое приложение»

3: Запоняем поле «Название»
4: Выбираем в разделе права «Яндекс.Метрика» и ставим галочку напротив пункта «Получение статистики, чтение параметров своих и доверенных счетчиков»

5: Нажимаем на ссылку «Подставить URL для разработки» под полем «Callback URL»
6: Нажимаем «Сохранить»

7: На открывшейся странице копируем ID приложения (его также можно скопировать увидеть в URL страницы)

8: Авторизуемся на Яндексе под учеткой пользователя, от имени которого будет работать приложение. (Вы можете получать данные с разных логинов Яндекс.Метрики используя одно и то же приложение, только для этого нужно сначала выдать каждому логину свой токен доступа.)
9: Переходим по URL: https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения> (В моем случае URL будет такой: https://oauth.yandex.ru/authorize?response_type=token&client_id=e01d9189ff1544488ae9c9c3dae45b58 и этот URL будет действителен и для вас, и токен вы получите, но лучше создайте свое приложение и укажите свой id)
10: Приложение запросит разрешение на доступ, которое нужно предоставить, нажав «Разрешить»:

11: После чего мы получим токен:

Скопируйте и сохраните его. Этот токен позволит получать данные Яндекс.Метрики для счетчиков того логина, которому вы выдали разрешение на доступ. Срок действия токена большой, если честно даже не знаю насколько большой. Для другого логина нужен будет другой токен, его легко получить перейдя по https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения>. Если приложению уже предоставлен доступ, то повторно перейдя по адресу мы снова получим тот же токен, что был выдан ранее.

5. Структура запроса к API

Итак, у нас есть токен и теперь мы можем делать запрос. В качестве примера токена я буду использовать тестовый токен, указанный в документации Яндекс.Метрики:
05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

В API Метрики есть несколько типов запросов:

  • Таблица
  • Drill down
  • Получение данных по времени
  • Сравнение сегментов
  • Сравнение — drill down

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

Запрос «Таблица» вытягивает «плоские» табличные данные, тогда как «Drill down» отдает иерархически вложенные друг в друга данные. Эта логика есть и в интерфейсе. Переключитесь между видом «Линейный список» и «Древовидный список»:

Вид «Древовидный список» удобен для анализа данных в интерфейсе: в поиске озарения можно углубляться и углубляться в данные до тех пор пока не кончатся группировки. Вид «линейный список» удобнее для анализа с помощью табличных процессоров (например, Excel) или обработки с помощью SQL-запросов, в датафрейме R или Pandas. Когда группировок много, «плоский» вид данных несомненно выигрывает, так как позволяет быстро манипулировать всеми доступными данными, а иерархический список жестко привязывает нас к заданной иерархии вложенности группировок.

Запрос к API Метрики — это обычный GET-запрос, который можно выполнить из браузера. Этот запрос представляет собой основной URL «https://api-metrika.yandex.ru/stat/v1/data», вопросительный знак «?» и дальше идут параметры запроса, которые перечисляются через знак «&». Параметров запроса много, но я коснусь только основных. Упрощенно структура запроса выглядит так:

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

В одну строку это выглядит так: https://api-metrika.yandex.ru/stat/v1/data?metrics=<string>&dimensions=<string>&date1=<string>&date2=<string>&limit=<integer>&offset=<integer>&ids=<int,int,...>&oauth_token=<string>

Обязательными параметрами являются только metrics, oauth_token и ids.

6. Формируем запрос к API

Начнем составление нашего запроса к API

1 — В параметре metrics нужно перечислить список метрик. Они разделяются через запятую. Наименования метрик чувствительны к регистру. Максимальное число метрик в запросе — 20. Со списком метрик уровня визитов можно ознакомиться по ссылке. Чаще всего в отчетах нужны именно эти метрики, поэтому метрики уровня хита (просмотра) я в этой статье рассматривать не буду. Основные из метрик:

  • ym:s:visits — количество визитов
  • ym:s:pageviews — суммарное количество просмотров страниц
  • ym:s:users — количество уникальных посетителей (за отчетный период)
  • ym:s:bounceRate — показатель отказов
  • ym:s:pageDepth — глубина просмотра
  • ym:s:avgVisitDurationSeconds — средняя продолжительность визитов в секундах
  • ym:s:goal<goal_id>reaches — количество достижений цели, где вместо надо подставить идентификатор цели (зайдите в настройки целей для конкретного счетчика, чтобы получить список их идентификаторов)
  • ym:s:sumGoalReachesAny — суммарное количество достижений всех целей

Для тестового запроса выберем метрики «Визиты» (ym:s:visits) и «Просмотры» (ym:s:pageviews):
metrics=ym:s:visits,ym:s:pageviews

2 — В параметре dimensions нужно перечислить список группировок. Группировки — это необязательный параметр и если их не задать, то в отчете будет представлена общая статистика по сайту. Они также как и метрики разделяются запятой, тоже чувствительны к регистру. Максимальное их число — 10 в одном запросе. Со списком группировок уровня визитов можно ознакомиться по ссылке. Группировки более разнообразны чем метрики. Лично я чаще всего сталкиваюсь с тем, что набор метрик в запросе всегда неизменен, а вот группировки применяю самые различные, в зависимости от стоящей задачи. Поэтому я бы порекомендовал подробно ознакомиться со списком доступных группировок.

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

  • ym:s:<attribution>SearchEngine> — поисковая система
  • ym:s:<attribution>SearchPhrase> — поисковый запрос
  • ym:s:startURL — посадочная страница

Для группировки по датам можно добавить параметр ym:s:date.

Мы видим в группировках параметр <attribution>. В некоторых группировках нужно задать атрибуцию трафика. Она определяет как сессии пользователей будут привязываться к источнику трафика. Например, если мы поставили атрибуцию по последнему источнику, то к конкретному источнику в отчете будут отнесены сессии посетителей, у которых этот источник был последним. Существует несколько типов атрибуции трафика:

  • first — атрибуция по первому источнику
  • last — атрибуция по последнему источнику
  • prev — атрибуция по предыдущему источнику
  • lastSign — атрибуция по последнему значимому источнику (значимым считается любой источник, отличный от прямых и внутренних переходов).

Атрибуция в группировках задается с помощью параметризации и тут существует два способа:

  • Подставить вместо <attribution> один из типов (first, last или lastSign) (например, ...&dimensions = ym:s:lastSignSearchEngine&...)
  • Оставить <attribution> в группировке и добавить в запрос параметр attribution (например ...&dimensions = ym:s:<attribution>SearchEngine&attribution=lastSign...)

Для тестового запроса выберем группировку «Источник трафика» (ym:s:referer):
dimensions=ym:s:referer

О чем еще важно знать:

  1. Существует разделение области действия группировок и метрик на «визиты» и «хиты». Это разделение важно учитывать во внимание при запросах к API, нельзя использовать вместе измерения или метрики, которые относятся к разным областям применения. Группировки и метрики, начинающиеся с «ym:s:», имеют область действия «визиты» (s — session), а группировки и метрики, начинающиеся с «ym:pv:» относятся к «хитам» (pv — pageview — просмотр страницы).
  1. Есть группировки, которые могут принимать в определенных случаях пустое значение (null). Например, группировка «поисковая фраза» будет принимать какое-то значение только, когда есть информация о поисковой фразе. Ясно, что если переход был, к примеру, из социальной сети, то поискового запроса там и в помине не будет. Поэтому если группировка стоит первой в перечне, то в ответе будут отображены только те данные, где группировка не принимает пустое значение.

3 — date1 — дата начала отчетного периода в формате YYYY-MM-DD (например, 2015-08-31). Кроме абсолютных значений в формате YYYY-MM-DD можно задавать относительные значения:

  • today — сегодняшняя дата
  • yesterday — вчерашняя дата
  • ndaysAgo — n дней назад от сегодняшней даты, где вместо n надо указать количество дней, например 30daysAgo.

Если не задать начальную дату, то применится значение по умолчанию — 6daysAgo (6 дней назад от текущей даты).

Поставим в качестве даты начала отчета 1 января 2015 года:
date1=2015-01-01

4 — date2 — дата окончания отчетного периода в формате YYYY-MM-DD. Формат такой же как у date1. Важно, чтобы date2 не была меньше date1, а так date2 может быть даже в будущем, запрос будет работать.

Конечная дата date2 в нашем отчете будет вчерашним днем:
date2=yesterday

5 — параметр limit — ограничение на количество возвращаемых результатов. По умолчанию — 100, но максимум — 10000. Я чаще всего во всех запросах использую limit=10000, этого хватает для большинства запросов, но бывает, что отчет возвращает больше строк и тогда нам поможет следующий параметр.

В нашем запросе будем получать максимум — 10000 строк:
limit=10000

6 — параметр offset определяет первую строку выборки, значение по умолчанию — 1, что означает, что отчет будет генерироваться с первой строки. Этот параметр полезен, когда отчет содержит больше чем 10000 строк. Предположим, у нас больше 10000 строк. Первым запросом с offset=1 и limit=10000 мы выгрузим первые 10000 строк. Установив offset=10001 мы выгрузим данные, начиная с 10001 строки, при limit=10000 это означает, что будут выгружены строки 10001-20000. Если данных больше, чем 20000, то нужно сделать третий запрос, увеличив offset еще на 10000. И так далее в зависимости от объемов данных.

Устанавливаем первую строку:
offset=1

7 — ids содержит перечень идентификаторов счетчиков. Это поле поддерживает более одного значения, это значит мы можем одним запросом выгружать данные с нескольких счетчиков.

Для нашего тестового запроса возьмем значения ids=2138128,2215573.

Важно помнить, что если мы включаем в отчет данные более чем 1 счетчика, то они будут сгруппированы по тем группировкам, которые мы задали в dimensions. Это означает, что для того, чтобы разделить данные на отдельные сайты нужно передать в отчет какой-то параметр, который будет точно идентифицировать каждый из сайтов, например, добавить группировку «Домен страницы входа» (ym:s:startURLDomain).

Тогда полный список наших группировок будет таким:
dimensions=ym:s:referer,ym:s:startURLDomain

8 — параметр oauth_token — это авторизационный токен. Для каждого пользователя (логина Метрики) должен быть свой токен. Если запросить данные по счетчикам, воспользовавшись другим токеном, не подходящим к пользователю, то запрос возвратит сообщение об ошибке.

Мы будем использовать тестовый токен, указанный в документации:
oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Итак, мы собрали наш запрос по кусочкам и вот что получили:

https://api-metrika.yandex.ru/stat/v1/data?metrics=ym:s:visits,ym:s:pageviews&dimensions=ym:s:referer,ym:s:startURLDomain&date1=2015-01-01&date2=yesterday&limit=10000&offset=1&ids=2138128,2215573&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

7. Выполняем запрос

Теперь вставим запрос в адресную строку браузера и выполним его, перейдя по URL (ну или просто перейдите по ссылке выше).

Получили вот такой ответ:

Не стоит пугаться, это ответ в формате JSON. На самом деле, это крайне удобный формат данных, но пригоден он для использования в программировании, формировании post-запросов на веб-сервера, а вот человеку не очень просто быстро в нем разобраться. Чтобы облегчить эту задачу сделаем JSON более «красивым», добавив к запросу параметр pretty=true:

https://api-metrika.yandex.ru/stat/v1/data?metrics=ym:s:visits,ym:s:pageviews&dimensions=ym:s:referer,ym:s:startURLDomain&date1=2015-01-01&date2=yesterday&limit=10000&offset=1&ids=2138128,2215573&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037&pretty=true

Теперь стало чуть более понятно:

Верхушка ответа от API — это параметры нашего запроса (выделена желтым). Тут стоит обратить внимание на параметр dimensions. Это те группировки, что мы указали в своем запросе (выделены красной рамкой). А ниже metrics (выделены синей рамкой):

После перечисления параметров идет ответ от API. Ответ содержится в параметре data, он представлен в виде массива данных, заключенных в квадратные скобки. Этот массив — множество строчек данных, каждая из которых заключена в фигурные скобки. Я обвел один элемент массива оранжевой обводкой — это одна строка данных:

Внутри каждой строки есть dimensions (обведены красным) и metrics (обведены синим). Это значения наших группировок, они указаны в том порядке, в котором идут в параметрах запроса. Значит для этой строки данных:

  • ym:s:referer=«https://google.ru/»
  • ym:s:startURLDomain=«help.yandex.ru»
  • ym:s:visits=57136.0
  • ym:s:pageviews=120931.0

В интерфейсе Метрики эта строчка выглядела бы так:

JSON, как я уже сказал, не самый человекопонятный вид данных, но только в JSON-формате API отдает важный параметр total_rows — общее количество строчек, доступных по заданному запросу. Чтобы найти этот параметр нужно перейти в самый конец страницы:

В нашем случае total_rows = 94629, а это значит, что нам пришлось бы сделать еще 9 запросов, итеративно увеличивая offset на 10000, чтобы выгрузить все данные.

Но оставим JSON разработчикам. Для «обывателей» (надеюсь никто не обидится) Метрика может отдавать данные в CSV. Всё, что для этого нужно — после data в запросе поставить параметр «.csv», тогда URL нашего запроса будет выглядеть так:

https://api-metrika.yandex.ru/stat/v1/data.csv?metrics=ym:s:visits,ym:s:pageviews&dimensions=ym:s:referer,ym:s:startURLDomain&date1=2015-01-01&date2=yesterday&limit=10000&offset=1&ids=2138128,2215573&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037 (обратите внимание, что я убрал pretty=true, т. к. для CSV-запроса он не нужен)

После того как мы сделаем запрос по этому URL, загрузится файл data.csv:

Загруженный CSV (Comma-separated values) представляет собой обычный текстовый файл в кодировке UTF-8, где значения разделены запятыми:

Перед нами наши данные в значительно более привычном виде. Сначала идет заголовок таблицы, тут уже нет никаких ym:s:referer и названия группировок и метрик отображаются также как и в интерфейсе. Затем идет строчка с итоговыми данными (по всей выборке, а не только по выгруженным 10000 строкам), а после идут строки с данными. Их 10000. Если мы хотим выгрузить остальное — надо делать ещё запросы (изменяя offset).

8. Импорт в Excel

CSV очень просто загрузить в Excel, воспользовавшись функцией «Получение внешних данных из текста», которая находится в разделе «Данные»:

Сначала указываем путь к данным:

Указываем, что наши данные содержат разделители и задаем кодировку файла UTF-8:

Далее указываем используемый разделитель «запятая» и нажимаем «Готово»:

Помещаем данные на имеющийся или новый лист и вуаля:

#9. Заключение
Таким образом, формирование нужных отчетов Яндекс.Метрики, которые будут в несколько кликов доступны для анализа, сводится к тому, чтобы:
а) сделать нужный URL запроса
б) запросить данные через браузер и скачать csv-файл
в) открыть csv-файл в Excel или любом другом табличном процессоре или приложении анализа данных

У запроса даже не нужно менять даты, потому что можно пользоваться такими параметрами: date1=7daysAgo&date2=yesterday. Такой запрос будет выбирать данные за последнюю неделю.

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

Отчет по Директу для поисковых кампаний
https://api-metrika.yandex.ru/stat/v1/data.csv?dimensions=ym:s:directSearchPhrase,ym:s:directClickOrder,ym:s:directBannerGroup,ym:s:directClickBanner,ym:s:directPhraseOrCond,ym:s:UTMSource,ym:s:UTMMedium,ym:s:UTMCampaign,ym:s:UTMContent&metrics=ym:s:visits,ym:s:pageviews,ym:s:bounceRate,ym:s:avgVisitDurationSeconds,ym:s:sumGoalReachesAny&filters=ym:s:directPlatformType=='search'&limit=10000&offset=1&ids=31458&oauth_token=53e1a43ac4af43be73e0ba2c4b&include_undefined=true

Отчет по Директу для кампаний РСЯ
https://api-metrika.yandex.ru/stat/v1/data.csv?dimensions=ym:s:directPlatform,ym:s:directClickOrder,ym:s:directBannerGroup,ym:s:directClickBanner,ym:s:directPhraseOrCond,ym:s:UTMSource,ym:s:UTMMedium,ym:s:UTMCampaign,ym:s:UTMContent&metrics=ym:s:visits,ym:s:pageviews,ym:s:bounceRate,ym:s:avgVisitDurationSeconds,ym:s:sumGoalReachesAny&filters=ym:s:directPlatformType=='context'&limit=10000&offset=1&ids=31458&oauth_token=53e1a43ac4af43be73e0ba2c4b&include_undefined=true

Отчет по ключевым словам из ПС с детализацией по целевым страницам и поисковым запросам
https://api-metrika.yandex.ru/stat/v1/data.csv?dimensions=ym:s:lastSearchEngine,ym:s:lastSearchPhrase,ym:s:startURL&metrics=ym:s:visits,ym:s:pageviews,ym:s:bounceRate,ym:s:avgVisitDurationSeconds,ym:s:sumGoalReachesAny&filters=ym:s:lastTrafficSource=='organic'&limit=10000&offset=1&ids=31458&oauth_token=53e1a43ac4af43be73e0ba2c4b&include_undefined=true
(Используется атрибуция last)

Отчет по источникам трафика, детальным источникам трафика, реферерам и целевым страницам
https://api-metrika.yandex.ru/stat/v1/data.csv?dimensions=ym:s:lastTrafficSource,ym:s:lastSourceEngine,ym:s:referer,ym:s:startURL&metrics=ym:s:visits,ym:s:pageviews,ym:s:bounceRate,ym:s:avgVisitDurationSeconds,ym:s:sumGoalReachesAny&limit=10000&offset=1&ids=31458&oauth_token=53e1a43ac4af43be73e0ba2c4b&include_undefined=true
(Используется атрибуция last)

О чем еще важно помнить:

  • В документации ей всё, ну или почти всё (есть кое-что, что не описано :). Например, есть полный список группировок и метрик
  • Один запрос содержит не более 10 измерений, не более 20 метрик
  • Не все группировки и метрики (одинаково полезны) совместимы (ym:s: и ym:pv:), также нельзя вместе применять некоторые группировки Директа с другими группировками (например, нельзя сделать группировку по часам или по городам, если есть группировка Директа)
  • На одного пользователя (один логин) есть ограничение в 5000 запросов в день

Успехов в автоматизации! Она заставляет поверить, что в мире есть место «магии». А еще даёт возможность убить тупую рутину и больше времени посвящать размышлениям и творчеству :)

Как конвертировать JSON в CSV

12 мая 2015, 0:56

JSON (JavaScript Object Notation) — отличный формат данных, но все его прелести раскрываются, когда работаешь с ним в коде. А вот работать с ним в Экселе совсем неудобно, и тогда нужно конвертировать его в CSV. По запросу «json to csv converter» Гугл выдает кучу различных сервисов, но мне больше всего приглянулся этот.

Добавить JSON в сервис можно одним из трех способов:

  1. Сохранить JSON как файл и указать путь к файлу
  2. Ввести URL с запросом и нажать «Load URL»
  3. Вставить текст JSON

Можно выбрать нужный разделитель для CSV (Output Field Separator).
После того как данные появились в поле для входных данных, нажимаем «Convert JSON to CSV»:

На выходе получаем данные в табличной структуре, разделенные запятой:

Особенность преобразования в том, что сложные объекты JSON'а с многими уровнями вложенности приводятся к простейшему ассоциативному массиву (словарю):

Что потом с этим делать? В первую очередь, открыть CSV в Экселе:

Данные разбиты на 2 строки: в первой строке ключи, во второй — значения. Удобнее будет работать с этими данными если их транспонировать: копируем данные и вставляем на новый лист с транспонированием. Должно получится что-то подобное:

Вот теперь с этим уже можно работать. Например, применить фильтр, который оставит только те пары значение-ключ, у которых ключ содержит «children» и «name»:

Или оставить данные, содержащие «result» и «children», и затем разбить ключи по разделителю «точка» через функцию «Текст по столбцам»:

Естественно, эти методы обработки данных пригодны только для данных из моего примера, но их можно использовать и на других данных, комбинируя формулы и функции Экселя, например, можно искать какой-то маркер в ключе с помощью функции ПОИСК. В принципе, сводится всё к одному: придумать как по ключу получить нужные значения.

JSON из примера можно скачать по ссылке.

Список стоп-слов Яндекс.Директа

11 мая 2015, 22:31

Стоп-слова в Яндекс.Директе — это служебные части речи и местоимения, а также любые слова, не несущие дополнительного смысла, которые автоматически исключаются из запроса пользователя при отборе объявлений для показа. Например, при запросе пользователя “Как и когда купить слона” для показа будут отобраны объявления, у которых в ключевых словах присутствует фраза “Купить слона”. “Как”, “и”, “когда” будут в этом случае являться стоп-словами. Для их принудительного включения во фразу перед ними нужно поставить знак плюс, например «+как +и +когда купить слона».

Не путайте стоп-слова и минус-слова. Минус-слова — это слова, по запросам с которыми рекламное объявление показываться не будет. Минус-слова можно указать на уровне кампании, группы объявлений или ключевой фразы. Например, если мы укажем минус-слово «скачать» на уровне кампании, то ни одно из объявлений кампании не будет показываться по любым поисковым запросам пользователя, содержащим «скачать».

Мне понадобилось определить какие слова Яндекс.Директ считает стоп-словами. Сначала я задумал использовать для этой задачи список всех предлогов, союзов, междометий и местоимений. Но оказалось, что не все слова этих частей речи используются Директом в качестве стоп-слов. Например, союз «со» и предлог «между» к стоп-словам не относятся. Проверить это просто: если в сервис прогноза бюджета добавить предлог «в» и нажать «Посчитать», то сервис сообщит об ошибке:

А попытка рассчитать бюджет для предлога «между» закончится успехом:

Другой способ определить стоп-слова — с помощью Вордстата. Количество показов по фразам «небо земля» и «небо и земля» одинаковое. Это означает, что союз «и» не учитывается при показе объявлений в Директе:

Фраза «между небом и землей» обладает другим количеством показом, значит наличие предлога «между» во фразе уменьшает количество показов:

Вордстат при расчете количества показов для фразы, состоящей только из стоп-слова, возвращает 0. В этом он отличается от сервиса прогноза бюджета (который, напомню, выдает ошибку).

Но Вордстат возвратит тот же ноль и при запросе любого слова, у которого вообще нет показов:

Так что использовать Вордстат для определения стоп-слов не совсем надежно, поэтому я решил использовать сервис прогноза бюджета, он позволяет массово загружать несколько фраз и уведомляет о том какие именно слова не позволяют рассчитать бюджет:

Итак, я взял свой список предлогов, союзов, междометий и местоимений и начал опрашивать все слова в сервисе прогноза бюджета, но внезапно оказалось, что глагол «есть» — это тоже стоп-слово:

Значит список стоп-слов Яндекса не ограничивается одними лишь служебными словами и местоимениями. После этого открытия мне ничего не оставалось кроме как взять список кириллических униграмм (однословников) с OpenCorpora и прогнать их все в сервисе прогноза бюджета.
Следующим открытием было то, что ограничиваться одними лишь кириллическими словами было ошибкой:

Поэтому в список слов для проверки были добавлены англоязычные униграммы. Найти англоязычный корпус оказалось не так легко, но всё же удалось получить 5000 наиболее популярных англоязычных лемм.

Итоговый список получился таким:

a
about
all
am
an
and
any
are
as
at
be
been
but
by
can
could
do
for
from
has
have
i
if
in
is
it
me
my
no
not
of
on
one
or
so
that
the
them
there
they
this
to
was
we
what
which
will
with
would
you
а
будем
будет
будете
будешь
буду
будут
будучи
будь
будьте
бы
был
была
были
было
быть
в
вам
вами
вас
весь
во
вот
все
всё
всего
всей
всем
всём
всеми
всему
всех
всею
всея
всю
вся
вы
да
для
до
его
едим
едят
ее
её
ей
ел
ела
ем
ему
емъ
если
ест
есть
ешь
еще
ещё
ею
же
за
и
из
или
им
ими
имъ
их
к
как
кем
ко
когда
кого
ком
кому
комья
которая
которого
которое
которой
котором
которому
которою
которую
которые
который
которым
которыми
которых
кто
меня
мне
мной
мною
мог
моги
могите
могла
могли
могло
могу
могут
мое
моё
моего
моей
моем
моём
моему
моею
можем
может
можете
можешь
мои
мой
моим
моими
моих
мочь
мою
моя
мы
на
нам
нами
нас
наса
наш
наша
наше
нашего
нашей
нашем
нашему
нашею
наши
нашим
нашими
наших
нашу
не
него
нее
неё
ней
нем
нём
нему
нет
нею
ним
ними
них
но
о
об
один
одна
одни
одним
одними
одних
одно
одного
одной
одном
одному
одною
одну
он
она
оне
они
оно
от
по
при
с
сам
сама
сами
самим
самими
самих
само
самого
самом
самому
саму
свое
своё
своего
своей
своем
своём
своему
своею
свои
свой
своим
своими
своих
свою
своя
себе
себя
собой
собою
та
так
такая
такие
таким
такими
таких
такого
такое
такой
таком
такому
такою
такую
те
тебе
тебя
тем
теми
тех
то
тобой
тобою
того
той
только
том
томах
тому
тот
тою
ту
ты
у
уже
чего
чем
чём
чему
что
чтобы
эта
эти
этим
этими
этих
это
этого
этой
этом
этому
этот
этою
эту
я
мені
наші
нашої
нашій
нашою
нашім
ті
тієї
тією
тії
теє

Список не претендует на полную точность и вполне вероятно, что существуют еще какие-то стоп-слова. Учитывая, что у Яндекса есть турецкий поиск, то должны быть специфичные для этого языка стоп-слова.

Немного интересных и необъяснимых аномалий:

  • В список стоп-слов Яндекс.Директа входит слово «наса» (предполагаю, что это что-то вроде склонения слова «нас»).

Но Вордстат не считает его стоп-словом:

Количество показов для фраз «астронавт скотт келли» и «астронавт наса скотт келли» будет разным:

Но сервис прогноза бюджета не пропускает обе эти фразы и оставляет первую из них:

А рассчитать бюджет по фразе «что такое наса» сервис вообще не даст, так как она полностью состоит из стоп-слов (чтобы посчитать нужно добавлять плюсы перед словами):

Судя по тому, что количество показов для фраз «астронавт скотт келли» и «астронавт наса скотт келли» всё-таки разное, «наса» не является стоп-словом в том плане, что оно учитывается при показе объявлений, а уведомление об ошибке в сервисе прогноза бюджета — это баг Яндекса.

  • Есть странные стоп-слова: «оне», «емъ», «комья», «томах», «имъ».
    Но судя по разнице в количестве показов это всё стоп-слова только для валидатора сервиса прогноза бюджета:

Скорее всего, это тоже баг Яндекса.

  • Есть некоторые слова, которые в Вордстате имеют количество показов больше 0, но прогноз бюджета Яндекс.Директа говорит о том, что слово является стоп-словом. Например, слово «будете» — это стоп-слово для сервиса прогноза бюджета:

Но не стоп-слово для Вордстата:

Если взять фразы «будете пить колу» и «пить колу», то количество показов у них различается, а значит «будете» всё же учитывается при показе объявлений:

Таких «псевдо-стоп-слов» (которые стоп-словами не являются, но на них ругается валидатор сервиса прогноза бюджета) я обнаружил довольно-таки много:

будете
будучи
едим
едят
ел
ела
ем
емъ
ест
ешь
имъ
комья
наса
оне
сама
сами
самим
самими
самих
само
самого
самом
самому
саму
томах
тою
этою
am
could
me
them
мені
наші
нашої
нашій
нашою
нашім
ті
тієї
тією
тії
теє

Фактически, эти слова учитываются при показе объявлений и стоп-словами не являются. Я включил их в список стоп-слов, так как завязывался на получение данных из API Яндекс.Директа с помощью метода CreateNewForecast. Этот метод не позволяет создать новый расчет если фраза состоит только из стоп-слов, поэтому мне нужно было точно знать список стоп-слов, которые не принимает метод. Использовать ли полный список или список без этих слов-аномалий — это зависит от решаемой задачи.

UPD: Благодаря Татьяне Михальченко и Олегу Саламаха список пополнился украинскими стоп-словами.

Книга «Вероятностное программирование и байесовские методы для хакеров»

11 мая 2015, 13:43

Наткнулся на книгу «Probabilistic Programming and Bayesian Methods for Hackers» («Вероятностное программирование и байесовские методы для хакеров»). Книга представляет собой практическое руководство по вероятностному программированию, снабжена большим количеством примеров на Python.