Пошаговое руководство по работе с API Яндекса для непрограммистов

Большинство рекламодателей и специалистов по настройке рекламы знают, зачем нужны Яндекс.Аудитории. Один из самых востребованных вариантов – сегменты на основе геолокации. Что может быть проще? Рисуете на карте полигоны или загружаете адреса, указываете радиусы и задаете условия взаимодействия людей с локациями. ⠀

Через несколько часов аудитории готовы: они расскажут про ваш бизнес всем, кто подходит под критерии и пользуется интернетом. Но проходит время. Люди, входившие в аудитории, оказываются недоступны. Или вы получаете доступ к аудитории, созданной кем-то другим. И вот вы уже не помните и не понимаете, вокруг каких локаций и с какими условиями настроены аудитории, даже если они понятно названы. Знакомая ситуация?

Возможности веб-интерфейса Яндекс.Аудиторий по работе с готовыми сегментами сильно ограничены. Максимум вы можете:

• найти похожих пользователей,
• поделиться сегментом с кем-нибудь,
• придумать ему другое название,
• удалить.

Первые 3 действия требуют четкого понимания того, что именно содержится внутри. Поэтому ревизия давно забытых или чужих аудиторий нередко заканчивается действием 4 и созданием нового сегмента с названием, «по которому точно никогда не забуду, кто там находится».

Вспоминаем все

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

1. зовете программиста, который покажет свой кунг-фу Python этому Яндексу;
2. гуглите и пытаетесь сами во всем разобраться;
3. повторяете за мной и пользуетесь стандартными инструментами специалистов по контекстной рекламе и интернет-маркетологов (например, Excel), а заодно повышаете свою квалификацию.

Хотя мы будем работать напрямую с API Яндекса, никакие навыки программирования не понадобятся.Получить координаты точек из аудитории можно в Excel, но интереснее увидеть их на карте, поэтому предлагаю воспользоваться Power BI. Он покажет их прямо на дашборде (в Excel все аналогично, но о нем – в самом конце).

Устанавливаем Power BI

Скачайте и установите Power BI Desktop. Программа только для Windows, поэтому маководам нужно использовать Parallels Desktop. Регистрация не обязательна: и без нее все замечательно работает.

Шаг 1. Получаем токен для доступа к API Яндекса

Токен – это своего рода пароль, который помогает API Яндекса вас узнавать и отвечать на запросы вашей программы, предоставляя нужные данные. Чтобы его получить, нужно зарегистрировать новое приложение по этой инструкции или воспользоваться моей ссылкой для получения токена.

Но где же моя ссылка? Хочу предупредить: полученный по ссылке токен категорически не рекомендуется давать никому, даже мне. Его обладатель получит доступ к чтению статистики и изменению Яндекс.Метрики, Яндекс.Аудиторий и Яндекс.Директа.

Узнаю ли я ваш токен без вашего ведома? Нет. Вы получите его на странице Яндекс (убедитесь сами по адресной строке), поэтому токен увидите только вы и сам Яндекс.

Сможете ли вы отключить или поменять токен? Да. Достаточно поменять пароль аккаунта Яндекс или отозвать доступ на странице Яндекс.Паспорта в разделе «Входы и устройства» > «Устройства, сервисы и программы».

Зарегистрируйте собственное предложение (на самом деле это просто) или пройдите по этой ссылке на страницу авторизации Яндекса.

Убедитесь, что вы залогинены в нужном аккаунте, и разрешите доступ к нему для приложения Power BI connector.

После нажатия на большую желтую кнопку вы увидите токен.

Пока не закрывайте эту страницу!

Шаг 2. Находим полный список аудиторий

Запустите Power BI.

1. Нажмите нижнюю часть кнопки Get data («Получить данные»), чтобы открыть меню часто используемых источников данных.
2. В нижней части меню выберите пункт Blank query.

Откроется редактор Power Query.

Нажмите кнопку Advanced Editor для открытия расширенного редактора. Удалите весь имеющийся там код и вместо него вставьте этот:

let

    token = "", // вставьте свой токен между двойными кавычками

                header = [

        #"Authorization" = "OAuth " & token,

        #"Content-Type" = "application/json" // для GET списка сегментов

],

    Url = "https://api-audience.yandex.ru/v1/management/segments", // список сегментов

    Options = [

            Headers = header // заголовки запроса

    ],

     Source = Web.Contents(Url,Options),

    Json = Json.Document(Source),

    Segments = Json[segments],

     getFieldNames = (rec as any) => let

        names = List.Transform(rec, Record.FieldNames),

        combine = List.Combine(names)

    in

        if Value.Is(rec, type record)

        then Record.FieldNames(rec)

        else List.Distinct(combine),

                unpack = 

            Table.FromRecords(Segments,getFieldNames(Segments),MissingField.UseNull)

in

    unpack

Получится примерно следующее:

Теперь во вторую строку (token = “”) вставьте полученный токен между двойными кавычками и нажмите Done. Вы увидите таблицу с сегментами Яндекс.Аудиторий, к которым есть доступ у аккаунта с этим токеном.

Шаг 3. Достаем нужное и отсекаем лишнее

Среди вас наверняка найдутся те, кому не нужно объяснять, что делать дальше. Поэтому рассказываю тем, кто редко или неуверенно пользуется Power BI. Остальные могут воспринимать этот текст как совет, а не руководство к действию.

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

Для фильтрации:

1. В правой части заголовка колонки type нажмите кнопку с треугольником, направленным вершиной вниз, чтобы открыть меню фильтра.
2. Оставьте галочку только напротив значения geo.
3. Нажмите кнопку OК.

Убедитесь, что в колонке status остались только строки со статусом processed (готовые). Если это не так, отфильтруйте колонку status точно так же, как только что фильтровали колонку type. Картинка без комментариев:

Дальше предлагаю убрать лишние столбцы. Делать это не обязательно, но это хорошая привычка не раздувать модель данных, которая будет хранится в оперативной памяти компьютера.

1. Нажмите на кнопку Manage Columns.
2. Выберите пункт Choose Columns.
3. В открывшемся списке оставьте только колонки name и points.

У вас останется таблица из двух колонок: name – название аудитории из интерфейса Яндекс.Аудиторий, points – список географических координат точек внутри нее.

1. Нажмите кнопку с расходящимися в разные стороны стрелками рядом с заголовком колонки points.
2. В появившемся меню извлечения элементов из списка выберите Expand to New Rows («Развернуть в новые строки»).
3. Список координат по каждой аудитории распакуется в новые строки таблицы. В каждой строке будет находиться одна координата. Нужно извлечь оттуда широту и долготу.

1. Снова нажмите расходящиеся в разные стороны стрелки в правой части заголовка колонки points. Появится меню извлечения элементов из записи.
2. Просто нажмите OК.
3. Вы увидите 2 новые колонки: с географической широтой и долготой.
4. Теперь поменяйте тип данных в таблице:Переключитесь на вкладку Transform («Преобразования») и выделите все колонки, кликая по их заголовкам с зажатой кнопкой Shift (или нажмите Ctrl+A).
5. Нажмите Detect Data Type («Определить тип данных»).

Данные готовы для загрузки в модель.

Вернитесь на вкладку Home.

1. Нажмите Close & Apply («Закрыть и применить»).
2. Окно Power Query Editor автоматически закроется, данные начнут загружаться в модель.

Шаг 4. Рисуем карту

Вернитесь в Power BI Desktop. 

На панели Visualizations («Диаграммы») щелкните по диаграмме Map («Карта») с изображением глобуса.

На рабочей области появится заглушка карты, на месте которой появится сама карта.

1. Справа на панели Fields появятся загруженные данные с названиями колонок. Схватите мышкой колонку points.latitude и перетащите ее в поле Latitude («Широта») на панели Visualizations. Если в Visualizations не видите Latitude, то выберите заглушку карты щелчком мыши, и поле появится.
2. Повторите действие, перетащив мышкой points.longitude в поле Longitude («Долгота»).

Вы увидите карту с точками:

Ее можно передвинуть мышкой в любое место рабочей области и поменять размеры, схватив курсором за толстые маркеры по углам и сторонам. Точки всех аудиторий сейчас находятся в одной общей куче.

Срезы (слайсеры)

Схватите мышкой название колонки name и перетащите его в любое свободное место на рабочей области.Как только вы отпустите мышку, Power BI создаст новую диаграмму Table («Таблица») со списком аудиторий.

Не снимая выделения с таблицы аудиторий, щелкните мышкой по кнопке Slicer («Срезы») на панели Visualizations.

Теперь можете щелкать по названиям нужных аудиторий, и на карте будут отображаться только координаты принадлежащих им точек.

Больше не нужно гадать!

Шаг 5. Работаем в Excel

Шаги 2 и 3 можно сделать в Excel начиная с 2016-й версии (вообще можно с 2012-й, но понадобится что-то установить – гугл в помощь).Мне не нужно заново повторять эти шаги, поэтому просто копирую все, что сделал в Power BI. Сначала в Power BI нажимаю кнопку Transform data («Преобразовать данные»).

Открывается уже знакомый редактор запросов Power Query Editor, где:

1. Выбираю нужный запрос.
2. Захожу в расширенный редактор.
3. Копирую весь имеющийся там код в буфер обмена.

Показываю на примере Excel 2019 для Windows.

1. Переключитесь на вкладку «Данные».
2. Нажмите «Получить данные» для открытия контекстного меню.
3. Выберите группу «Из других источников».
4. Выберите пункт «Пустой запрос».

Откроется редактор Power Query.

1. Нажмите «Расширенный редактор».
2. Замените код в окне расширенного редактора на скопированный из Power BI или из начала статьи.
3. Нажмите «Готово».

Появится предупреждение о необходимости изменить параметры подключения.

1. Нажмите «Изменить учетные данные», появится окно «Доступ к веб-содержимому». 
2. Нажмите «Подключение».

Появится таблица, аналогичная таблице в Power Query. Нажмите «Закрыть и загрузить», и данные загрузятся на лист.

Что делать с ними в Excel? Можно добавлять в каждую аудиторию по одной точке и получить сервис прямого геокодирования, где адрес превращается в географические координаты (но есть и более удобные инструменты, о которых можем поговорить потом).

На самом деле в Excel можно делать почти все то же самое, что и в Power BI. Например, напрямую работать с API Яндекса. Сегодня мы научились загружать аудитории, но можно и подключиться к Яндекс.Метрике или получить статистику из Яндекс.Директ.

Заключение

Надеюсь, статья была полезна, и вы узнали новые способы работы с данными. Задавайте вопросы в комментариях! И пишите, что еще хотите узнать.

До новых встреч, Digital Lab!