Поскольку процесс выгрузки данных из Яндекс Директа и Яндекс Метрики по API очень схож, я бы хотел поделиться с вами бонусным материалом, который доступен пользователям онлайн-документации ETL для маркетолога – введением в работу с API Яндекс Метрики, чтобы у вас сложилось более глубокое понимание того, как выгружать статистику из рекламных и аналитических систем Яндекса.
Введение
Разумеется, за одно руководство невозможно в полной мере рассказать о всех тонкостях и нюансах работы с API Метрики, и даже кратко разобрать все API, которые есть у Яндекс Метрики. Однако мы надеемся, что материал, который вы прочтете ниже, расширит ваши навыки использования языка программирования Python, научит взаимодействовать с библиотеками сторонних разработчиков, а также познакомит вас с одним из API Метрики – API отчетов.
Итак, API сервиса Яндекс Метрика позволяет:
- управлять счетчиками, их настройками и правами доступа, не используя веб-интерфейс;
- получать информацию о посещаемости сайта и другие данные;
- формировать отчеты, в том числе с помощью сегментации и параметризации.
API Яндекс Метрики состоит из:
- API управления – позволяет управлять счетчиками, целями, фильтрами и другими объектами Яндекс.Метрики (создать счетчик, отредактировать его настройки, создать цель, выдать права доступа и т.п.).
- API отчетов – позволяет получать информацию о статистике посещений сайта и другие данные, не используя интерфейс Яндекс.Метрики. Поддерживает все возможности отчетов Яндекс.Метрики: сегментацию, полный набор группировок и метрик, сравнение сегментов и т.п.
- API, совместимый с Google Analytics Core Reporting API – поддерживает все возможности Google Analytics Core Reporting API (v3), но набор группировок и метрик ограничен.
API отчетов – это агрегированные или суммарные данные. Это означает то, что вы не сможете посмотреть отчеты в разрезе отдельных посещений. С помощью API отчетов не получится получить информацию о времени визита, Client ID этого визита, времени визита и т.д. Вы увидите только суммарные (итоговые и средние) данные, статистика по конкретному посещению или пользователю будет недоступна.
Агрегированные данные в отчетах Метрики
Заходя в интерфейс Яндекс Метрики, отчеты, которые вы анализируете — это и есть те самые агрегированные данные. Для получения неагрегированных данных (так называемые «сырые» данные) Яндекс Метрики используется Logs API.
Вы делаете запрос на те данные, которые хотите загрузить из Logs API и вам выдается большой и длинный список тех посещений пользователей, которые были на вашем сайте. Можно увидеть Client ID посещения, время пребывания на сайте, просмотры страниц многое другое.
Пример неагрегированных данных, выгруженных с помощью Logs API
Сырые данные передаются в стандартном формате tsv – такой файл можно легко импортировать в большинство систем управления базами данных. В их числе – ClickHouse, бесплатное открытое решение, на котором работает и сама Метрика. ClickHouse умеет обрабатывать сложные запросы в реальном времени, легко настраивается и не требует больших вычислительных ресурсов.
Сырые данные можно загрузить в свою базу данных и далее гибко ими управлять, а также объединять данные Яндекс.Метрики с другими источниками. Например, для построения сквозной аналитики.
Чем сырые данные отличаются от агрегированных?
Агрегированные, или обобщенные данные, которые вы видите в интерфейсе Метрики или выгружаете через API отчетов, рассчитываются для определенной группы визитов. Например, метрика «время на сайте» вычисляется для всех переходов из какого-либо источника трафика, всех визитов от посетителей мужского пола или всех визитов с планшетов.
А основой для этих расчетов служат сырые данные – записи об отдельных визитах или просмотрах. Таблица с этими записями и передается через Logs API, при этом каждая запись дополнена полезными сведениями из Метрики. Это подробные данные по Директу и по электронной коммерции, страна и город посетителя, а еще – различная техническая информация о визите: например, браузер и модель мобильного телефона.
Если вы зайдете в официальную документацию Яндекса, то увидите, что для каждого типа API существует свой раздел и перечень команд и запросов.
API Метрики в документации
Начало работы
Начало работы с API Яндекс.Метрикой аналогично шагам из Яндекс.Директа – вам необходимо зарегистрировать новое приложение и получить токен доступа.
Для регистрации приложения вам понадобится аккаунт разработчика на почте Яндекса. Для этого перейдите по адресу https://passport.yandex.ru/auth/reg и пройдите несложную процедуру регистрации.
Вам понадобится номер мобильного телефона, куда будут приходить СМС с кодами для входа в аккаунт. Если у вас уже есть аккаунт в Яндексе, вы можете использовать его, а не создавать новый.
Создание/вход в аккаунт Яндекса
После создания аккаунта перейдите по адресу https://oauth.yandex.ru/client/new. Для регистрации приложения не обязательно, чтобы было само приложение.
Заполните необходимые поля (со звездочкой *):
- Название сервиса
- Платформа приложения
- Доступ
В Название сервиса введите название приложения, которое будет использоваться. Вы можете задать произвольное имя. Например, MetrikaApp:
Название сервиса
К приложению можно прикрепить иконку приложения (максимальный размер не более 1Мб), но мы это делать не будем, поскольку данное приложение будет использоваться для личных целей, а не публично.
Напротив Платформы приложения поставьте галочку рядом с Веб-сервисы. Появится строка Redirect URI. Поставьте курсор мыши в это поле и в появившейся подсказке выберите Подставить URL для отладки:
Подставить URL для отладки
В это поле автоматически подставится адрес https://oauth.yandex.ru/verification_code:
https://oauth.yandex.ru/verification_code
Заполнение данного раздела вам понадобится в будущем для получения токена.
В разделе Доступ к данным поставьте две галочки для:
- Получение статистики, чтение параметров своих и доверенных счётчиков (metrika:read);
- Создание счётчиков, изменение параметров своих и доверенных счётчиков (metrika:write).
Доступ к данным
В разделе Почта для связи можно добавить e-mail для оповещений об изменениях во внешней авторизации. Этот шаг можно пропустить, так как он является необязательным.
Почта для свяжи (по желанию)
В самом конце страницы нажмите на кнопку Создать приложение. Приложение успешно создано. После этого вас автоматически перенаправит на другую страницу, где будут отображаться технические данные о вашем приложении. Они вам понадобятся через некоторое время.
Данные созданного приложения
Скопируйте идентификатор вашего приложения из раздела ClientID:
Копирование ClientID приложения
Сохраните его в обычном блокноте. Он вам понадобится чуть позже в запросах для получения OAuth-токена.
Теперь авторизуйтесь под учетной записью Яндекса, а затем перейдите по ссылке, вставив ее в адресную строку браузера: https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения>
, где вместо <идентификатор приложения> вставьте идентификатор вашего приложения, скопированного на предыдущем шаге.
https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения>
У вас должно открыться окно авторизации для аккаунта Яндекс Метрики. Нажмите кнопку Войти как… и тогда ваше приложение получит доступ к использованию API Яндекс Метрики.
Окно авторизации и подтверждение
На следующей странице отобразится ваш OAuth-токен. Он будет также добавлен в адресную строку.
Копирование OAuth-токена
Сохраните его и никому не показывайте и не передавайте. С его помощью можно получить доступ к вашей статистики Яндекс Метрики.
Установка PyCharm
В нашей онлайн-документации API Яндекс Директа мы используем программу для разработки на Python – PyCharm. Но вы можете использовать любую другую среду
Для начала написания программы необходимо установить среду разработки. Мы будем использовать PyCharm Community Edition — это IDE для профессиональной разработки на Python с подсветкой вариантов кода и отсутствием ошибок и неточностей.
Перейдите на сайт https://www.jetbrains.com/ru-ru/pycharm/
PyCharm
Нажмите кнопку Скачать. Выберите вашу операционную систему (ОС) и скачайте бесплатную версию Community, опустившись чуть ниже по страницы (проскроллив ее ниже). Скачивать нужно именно PyCharm Community Edition:
Скачивание PyCharm Community Edition
После загрузки запустите установщик. В открывшемся окне нажмите Next (Далее).
Начало установки
Выберите путь установки программы (кнопка Browse). Может изменить его на свой,может оставить по умолчанию. Желательно, чтобы в пути не было кириллицы (русских букв). Объем установки 1,4 Гб. Путь можно оставить по умолчанию, не изменяя его. Нажмите Next (Далее):
Выбор пути установки
В следующем окне поставьте галочки, как показано на скриншоте:
- Версия сообщества PyCharm
- Добавить «Открыть папку как проект»
- .py
Дополнительные настройки PyCharm
Затем нажмите Далее (Next). В следующем окне PyCharm возвращает новую папку в стартовом меню (Меню «Пуск»). Ничего не меняйте и нажмите Install (Установить).
Последний шаг перед установкой
Начнется установка PyCharm. Она может занять около 1-2 минут.
Установка PyCharm
В завершение установки поместите галочку, чтобы программа сразу запустилась. Нажмите Finish (Готово).
Установка PyCharm Community Edition завершена
Вам откроется окно программы PyCharm.
Первый экран программы PyCharm
Создание проекта
Создайте новый проект. Перейдите в меню File — New Project…
Создание нового проекта
Появится окно создания нового проекта. Здесь можно ничего не менять. Главное, чтобы в строке Base interpretator был выбран python.exe. Он должен находиться по адресу С:\Users\Имя пользователя\AppData\Local\Programs\Python\PythonXX\python.exe
, где Имя пользователя — имя текущего пользователя вашего компьютера, а XX — номер версии Python.
Настройки проекта
Если в данной строке нет пути к файлу, тогда его надо указать самостоятельно. Обязательно в окне выбора нажмите кнопку Show Hidden Files and Directories (Показывать скрытые файлы и папки), так как папка AppData является скрытой.
Show Hidden Files and Directories
После нажатия кнопки Create создается новый проект и открывается первый файл с названием main.py.
Новый проект с названием main.py
Он вам не понадобится. Создайте новый файл в новом проекте. Для этого нажмите правой кнопкой мыши на проекте, выберите New — Python File.
New — Python File
В следующем окне придумайте имя, введите его в поле Name и два раза кликните на Python File.
New Python file
В окне программы у вас появится еще одна вкладка с названием нового файла. Здесь вы и будете писать свой код на Python.
Установка библиотеки Python
Для работы с API Яндекс.Метрики мы предлагаем использовать библиотеку Павла Максимова. Она расположена по адресу https://github.com/pavelmaksimov/tapi-yandex-metrika
Поскольку библиотека является сторонней разработкой, ее необходимо установить. Для этого вернитесь в PyCharm и в меню сверху перейдите в File — Settings.
File — Settings
В открывшемся окне найдите раздел со своим проектом (1), затем выберите Python Interpreter (2), убедившись, что он выбран (а не отображается <No interpreter>), и добавьте новые библиотеки с помощью иконки с плюсиком (3).
Установка библиотек Python
Введите название библиотеки tapi-yandex-metrika, а затем нажмите Install Package. Вам нужно дождаться окончательной установки пакета и надписи Package [Название библиотеки] installed successfully внизу окна.
Установка библиотеки tapi-yandex-metrika
На этом предварительная настройка программы завершена. Теперь вы можете приступить к своему первому запросу к API отчетов Яндекс Метрики.
Первый запрос
Для начала попробуем поработать с API отчетов (API Stats). Код, который вам пригодится для запроса, расположен по адресу https://github.com/pavelmaksimov/tapi-yandex-metrika/blob/master/docs/stats.md
Используйте код, а точнее его часть из документации Максимова:
import datetime as dt
from tapi_yandex_metrika import YandexMetrikaStats
ACCESS_TOKEN = "ваш_токен"
COUNTER_ID = "идентификатор_яндекс_метрики"
client = YandexMetrikaStats(access_token=ACCESS_TOKEN)
params = dict(
ids=COUNTER_ID,
date1="2022-11-01",
date2=dt.date(2022,11,30),
metrics="ym:s:visits",
dimensions="ym:s:date",
sort="ym:s:date",
lang="en",
#ud5 Other params -> https://yandex.ru/dev/metrika/doc/api2/api_v1/data.html
)
report = client.stats().get(params=params)
В поле ACCESS_TOKEN вставьте ваш токен доступа, полученный на предыдущем шаге, а в поле COUNTER_ID – идентификатор счетчика Яндекс.Метрики, из которого вы хотите получить данные.
В поле date1 вы можете указать начальную дату выгрузки данных в формате YYYY-MM-DD (за какой период вы хотите получить статистику из счетчика Яндекс.Метрики), а в поле date2 – конечную дату отчета в формате YYYY-MM-DD. Также используйте значения: today, yesterday, ndaysAgo.
Примечание: date1 и date2 могут принимать и строку, и тип данных datetime с перечислением через запятую атрибутов (year, month, day).
Например, отчет с 1 по 30 ноября 2022 года будет выглядеть так:
Диапазон дат
В metrics вы через запятую можете перечислить перечень показателей, которые хотите выгрузить, в поле dimensions – группировки, они же параметры. Полный список группировок и метрик API отчетов Яндекс Метрики представлен в официальной документации Яндекса.
Не забудьте, что в Яндекс Метрике есть разные уровни организации данных. Нельзя использовать вместе измерения или метрики, которые относятся к разным областям применения.
Группировки и метрики, начинающиеся с ym:s:, имеют область действия визиты (s — session), а группировки и метрики, начинающиеся с ym:pv: относятся к хитам (pv — pageview — просмотр страницы).
Список группировок и метрик
В одном запросе вы можете передать до 20 показателей и 10 параметров.
Например, в качестве показателя для первого запроса будем использовать визиты на уровне визитов (ym:s:visits), а в качестве параметра – разбивку по дате (ym:s:date):
Пример параметра и показателя
Строка запроса sort=”ym:s:date“ отвечает за сортировку, в данном случае по дате. По умолчанию сортировка производится по убыванию (указан знак «-» перед группировкой или метрикой). Чтобы отсортировать данные по возрастанию, удалите знак «-».
lang=”en” – язык запроса. Подробнее о синтаксисе запроса API отчетов и о том, в каком виде вы получите ответ, читайте в документации Яндекса.
Последнее строчкой, перед тем как выполнить запрос, добавьте:
report = client.stats().get(params=params)
В самой программе это выглядит так:
Код программы в PyCharm
Чтобы увидеть результат на экране, добавьте строку print(report.data) и запустите программу. Если вы все сделали согласно документации, то в консоли отобразиться результат выполнения запроса:
Результат выполнения запроса
Вы можете перенести длинный текст на строчки ниже с помощью функции Soft-Wrap:
Изменение отображения результата запроса
Внизу таблицы API отчетов отдали дополнительные данные по запросу:
'total_rows': 30, 'total_rows_rounded': False, 'sampled': False, 'contains_sensitive_data': False, 'sample_share': 1.0, 'sample_size': 42534, 'sample_space': 42534, 'data_lag': 0, 'totals': [42473.0], 'min': [973.0], 'max': [1695.0] #ud5}
- total_rows – общее количество строк в ответе по всему множеству данных;
- total_rows_rounded – признак того, что общее количество строк было округлено (false – нет);
- sampled – признак семплирования. Показывает, был ли применен семплинг (false – нет, true – да);
- contains_sensitive_data – признак возможного отсутствия конфиденциальных данных в ответе. К ним относятся данные, которые рассчитываются алгоритмами Яндекса, например, социально-демографические (пол, возраст и др.), адреса страниц входа, поисковые фразы, информация о роботах. При значении true в ответе не отобразятся такие данные, если выборка составляет меньше 10 посетителей;
- sample_share – доля данных, по которым осуществлялся расчет. Доступно значение в пределах от 0 до 1;
- sample_size – количество строк в выборке данных;
- sample_space – количество строк данных;
- data_lag – задержка в обновлении данных, в секундах;
- totals – общие результаты для метрик по всему множеству данных;
- min – минимальные результаты для метрик среди попавших в выдачу ключей;
- max – максимальные результаты для метрик среди попавших в выдачу ключей.
В таком виде работать со статистикой не очень удобно. А поскольку полученные данные являются списком (type – list), вы можете преобразовать этот список в датафрейм:
result = report().to_values() print(result) print(type(result))
Результат запроса – список (type – list)
Для этого импортируйте библиотеку pandas с помощью команды:
import pandas as pd
Добавьте ее в самом начале программы после подключения библиотеки tapi-yandex-metrika:
import pandas as pd
Чтобы узнать названия столбцов, которые требуется задать в датафрейме, используйте команду:
print(report.columns)
В самой программе это будет отображаться так:
Названия столбцов print(report.columns)
Таким образом, вы получите итоговую конструкцию для удобочитаемого отображения данных, если используйте такие же параметры и показатели (ym:s:date и ym:s:visits), что в примере выше:
df = pd.DataFrame (result, columns = ['ym:s:date', 'ym:s:visits']) print (df)
В самой программе вы увидите такой результат выполнения программы:
Результат выполнения программы
Вы можете сравнивать результат запроса по визитам API с данными из интерфейса Яндекс Метрики. Для этого просто постройте соответствующий отчет, включая статистику по роботам:
Сравнение данных с интерфейсом Яндекс Метрики
Как видите, данные сходятся по каждому дню и суммарно.
По умолчанию в запросе возвращается только 100 строк отчета. Но с помощью параметра limit вы можете увеличить этот порог до 100 000. В отчете может быть больше строк, чем указано в limit. Тогда необходимо сделать несколько запросов для получения всего отчета.
Пример запроса, который идентичен интерфейсному отчету Источники, сводка, за неделю выглядит следующим образом:
import datetime as dt
from tapi_yandex_metrika import YandexMetrikaStats
import pandas as pd
ACCESS_TOKEN = "ваш_токен"
COUNTER_ID = "идентификатор_яндекс_метрики"
client = YandexMetrikaStats(access_token=ACCESS_TOKEN)
params = dict(
ids=COUNTER_ID,
date1="6daysAgo",
date2="today",
metrics="ym:s:visits,ym:s:users,ym:s:bounceRate,ym:s:pageDepth,ym:s:avgVisitDurationSeconds",
dimensions="ym:s:lastSignTrafficSource",
lang="en",
#ud5 Other params -> https://yandex.ru/dev/metrika/doc/api2/api_v1/data.html
)
report = client.stats().get(params=params)
result = report().to_values()
df = pd.DataFrame (result, columns = ['ym:s:lastSignTrafficSource', 'ym:s:visits', 'ym:s:users', 'ym:s:bounceRate', 'ym:s:pageDepth', 'ym:s:avgVisitDurationSeconds'])
print (df)
Для источника трафика (и других группировок) в запросе необходимо задавать дополнительную конструкцию для атрибуции <attribution>.
В самой программе это выглядит так:
Запрос для источников трафика с моделью атрибуции
Запустив команду, вы получите такой результат:
Результат выполнения запроса
Не всегда данные в консоли PyCharm отображаются полностью. Чтобы увидеть весь датафрейм без … добавьте в самом начале программы дополнительные строчки кода:
pd.set_option('display.width', 400)
pd.set_option('display.max_columns', 10)
Тогда вы увидите результат в полном виде:
Все результаты
Сравните итоговые данные с интерфейсными, открыв отчет в Яндекс Метрике. Проверьте, что вы выбрали тот же самый диапазон дат, оставили роботность (Данные: с роботами) и назначили одинаковую модель атрибуции:
Сравнение данных с интерфейсом Яндекс Метрики
Как видите, между интерфейсными данными и статистикой, выгруженной по API, есть различия. Она касается как округлений значений в сторону ближайшего целого числа, так и некоторых отличий в таблице. Например, в API нет трафика Не определено.
Чтобы сохранить полученные данные в Excel, воспользуйтесь функцией to_excel() (для .xlsx) или to_csv (для .csv). На предыдущем шаге мы получили датафрейм df. Теперь используйте команду с указанием пути на компьютере, чтобы сохранить таблицу в нужное место на компьютере. Например, вот так:
df.to_csv("C:/Users/Desktop/metrika_api.csv")
, где metrika_api – произвольное название вашего файла.
Сохраненный файл в формате .csv будет выглядеть так:
Выгрузка данных в формате .csv
С помощью функции Текст по столбцам вы сможете разделить один столбец на несколько, задав условие разделения. В данном случае – запятая, чтобы получить привычную таблицу для анализа:
Текст по столбцам
Сохраненный файл в формате .xlsx будет выглядеть чуть иначе:
Выгрузка данных в формате .xlsx
Примечание: для сохранения файла в формате .xlsx вам потребуется установить дополнительную библиотеку openpyxl
Визуализация данных
Статистику, которую вы получили, можно визуализировать прямо в PyCharm. В качестве примера постройте график по дате и визиту для первого запроса:
import datetime as dt
from tapi_yandex_metrika import YandexMetrikaStats
import pandas as pd
pd.set_option('display.width', 400)
pd.set_option('display.max_columns', 10)
ACCESS_TOKEN = "ваш_токен"
COUNTER_ID = "идентификатор_яндекс_метрики"
client = YandexMetrikaStats(access_token=ACCESS_TOKEN)
params = dict(
ids=COUNTER_ID,
date1="2022-11-01",
date2="2022-11-30",
metrics="ym:s:visits",
dimensions="ym:s:date",
lang="en",
#ud5 Other params -> https://yandex.ru/dev/metrika/doc/api2/api_v1/data.html
)
report = client.stats().get(params=params)
result = report().to_values()
df = pd.DataFrame (result, columns = ['ym:s:date', 'ym:s:visits'])
print (df)
Запустив программу, вы получите первоначальный результат:
Результаты запроса
Для создания статических, анимированных и интерактивных визуализаций в Python используется библиотека Matplotlib. Получаемые с помощью этого пакета изображения могут быть использованы в качестве иллюстраций в публикациях. В PyCharm данная библиотека уже установлена по умолчанию, вам остается ее только импортировать, добавив нижеприведенную строчку кода в самом начале программы:
import matplotlib.pyplot as plt
Все, что осталось сделать, это запустить команду на визуализацию:
df.plot(kind='bar',x='ym:s:date',y='ym:s:visits') plt.show()
, где:
- plot – команда на создание графика;
- kind=’bar’ – вертикальная столбчатая диаграмма;
- x – данные по оси X;
- y – данные по оси Y.
Выполнив команду, в отдельном окне вы получите визуализацию такого вида:
Визуализация данных
Вы можете задать названия осей с помощью команд:
df.plot(kind='bar',x='ym:s:date',y='ym:s:visits')
plt.xlabel("Дата") # название оси X
plt.ylabel("Визиты") # название оси Y
plt.title("Визиты по дням") # название графика
plt.show()
Название осей и название графика
Вы можете изменить тип визуализации с помощью параметра kind:
- line – линейный график (по умолчанию);
- bar – вертикальная столбчатая диаграмма;
- barh – горизонтальная столбчатая диаграмма;
- hist – гистограмма;
- box – ящик с усами (boxplot);
- kde – ядерная оценка плотности (Kernel Density Estimation, KDE);
- density – график плотности;
- area – диаграмма с областями;
- pie – круговая диаграмма;
- scatter – диаграмма рассеяния;
- hexbin – график с шестиугольной сеткой (hexagonal binning).
Классический график временного ряда – kind=’line’:
Изменение графика
Сохранить график на свой компьютер как изображение можно, нажав на иконку сохранения:
Сохранение графика
Доступны самые популярные форматы – png, jpeg, jpg, tiff, pdf.
Поздравляем! Вы познакомились с основными шагами по выгрузке данных из API отчетов Яндекс Метрики с помощью библиотеки стороннего разработчика, выполнили свой первый запрос и сохранили полученную статистику на компьютер, попутно выполнив несколько визуализаций с помощью пакета Matplotlib.
Продолжая изучать работу различных систем и программирование на Python применительно к интернет-маркетингу, вы всегда будете востребованы на рынке труда и сможете претендовать на самые лучшие позиции в топ-компаниях!
Полезные ссылки:
- Введение в API Яндекс Метрики – https://lib.osipenkov.ru/vvedenie-v-api-yandeks-metriki/
- API Яндекс.Метрики – https://yandex.ru/dev/metrika/
- Список группировок и метрик – https://yandex.ru/dev/metrika/doc/api2/api_v1/attrandmetr/dim_all.html
- Синтаксис запроса – https://yandex.ru/dev/metrika/doc/api2/api_v1/data.html
- tapi-yandex-metrika (GitHub) – https://github.com/pavelmaksimov/tapi-yandex-metrika
- API отчетов – https://github.com/pavelmaksimov/tapi-yandex-metrika/blob/master/docs/stats.md
- Просмотры (hits) – https://yandex.ru/dev/metrika/doc/api2/logs/fields/hits.html
- Визиты (visits) – https://yandex.ru/dev/metrika/doc/api2/logs/fields/visits.html
- Получение сводной таблицы – https://yandex.ru/dev/metrika/doc/api2/api_v1/pivot.html
