Что такое язык R и как работать с API рекламных систем Google AdWords и Яндекс.Директ с его помощью

47
2308

Если вы ведете несколько небольших рекламных кампаний в одном рекламном аккаунте, то для анализа их эффективности вам достаточно посмотреть нужные данные в Google AdWords / Яндекс.Директ и Google Analytics / Яндекс.Метрике. Но чтобы даже бегло оценить эффективность пары десятков рекламных кампаний в нескольких аккаунтах таким способом, вы потратите в лучшем случае несколько часов. А на детальный анализ могут уйти дни и недели, в течение которых рекламный бюджет будет тратиться и, возможно, далеко не самым эффективным образом.

В этой статье я расскажу, как автоматизировать работу с данными из Google AdWords и Яндекс.Директ с помощью двух пакетов, расширяющих базовые возможности языка R.

Я постарался изложить материал так, чтобы его мог использовать любой пользователь — даже тот, кто пока не написал ни одной строчки кода. Для этого вполне достаточно понимания, что такое функция, хотя бы в плоскости электронных таблиц Microsoft Excel или Google Spreadsheets. Возможно, для вас этот материал станет своеобразным толчком к изучению R.

Содержание статьи:

Что такое язык R

R — это язык программирования для статистической обработки данных и работы с графикой, а также свободная программная среда вычислений с открытым исходным кодом. Именно такое определение вы можете найти на страницах Википедии.

R был создан двумя сотрудниками статистического факультета Оклендского Университета Робертом Джентелменом и Россом Айхэкой. Свое название язык получил по первой букве имен его создателей.

Как я открыл для себя R или от 1С до R за 10 лет

От 1C до R за 10 лет

В начале статьи позволю себе небольшое отступление о том, как я вообще пришел к обработке данных в R.  Многие сейчас говорят о Big Data, но на самом деле не так много компаний, которым недостаточно простых табличных агрегаторов вроде Excel. Уверен, что мой путь поможет вам разобраться, на каком вы сейчас этапе.

С 2007 по 2009 год основной частью моей работы была разработка технических заданий для программистов 1С на внедрение каких-либо новых отчетов. Поскольку в то время была 1С версии 7.7., говорить о каком-либо интегрированном конструкторе отчетов не приходилось. Чтобы получить данные в каком-то новом срезе, приходилось писать ТЗ и ждать его обработки от программистов.

За пару лет я довольно неплохо разобрался с Microsoft Excel и поставил одно из своих последних ТЗ программистам 1С. Эта была одна большая выгрузка сырых данных по чекам, содержащая все возможные поля. Таким образом я  переехал из 1С в Excel, и табличный агрегатор от Microsoft был моим верным оруженосцем ближайшие несколько лет.

Возможно, я и сейчас бы использовал Excel, если бы он не был так прожорлив даже на выборке среднего объема. Если вам надо обработать пару десятков тысяч строк то, Excel с этим справится быстро и эффективно. Но наиболее внимательные пользователи офиса Microsoft заметили, что количество строк на рабочем листе последний раз поднималось в версии 2007 года и до сих пор даже в самых новых версиях составляет 1 048 576 строк и 16 384 столбца. И дело не в том, что Microsoft жалко добавить большее количество строк. Просто Excel слишком прожорлив на таких объемах данных, и обработка даже нескольких сотен тысяч строк займет всю вашу оперативную память. А в современном мире таблицей в миллион строк вряд ли кого-то удивишь.

Именно поэтому примерно в 2012 году я начал учить SQL. На обработку миллиона строк, даже при сложных запросах с использованием JOIN, в любой из популярных систем управления базами данных (СУБД) при нормально проиндексированных таблицах у вас уйдет не более минуты. Таким образом вопрос хранения и обработки данных я закрывал с помощью SQL, а для визуализации по прежнему использовал Excel.

В 2015 году Microsoft выпустил платформу Power BI — одно из лидирующих BI решений на данный момент. По сути, Power BI появилась как сбор надстроек над Excel, Power View (для создания интерактивных дашбордов), Power Query (для загрузки данных из различных источников) и PowerPivot (для создания модели данных и связи между таблицами). Это очень удобный инструмент для загрузки данных из множества различных источников, их очистки, построения модели данных и визуализации. Мы в Netpeak очень активно используем данную платформу для аналитики рекламных кампаний и эффективности отдела контекстной рекламы и  нашего корпоративного блога.

Т.к. задачу хранения данных закрывают СУБД (мы используем MySQL и Google BigQuery), а вопрос визуализации на 80% закрывает Power BI, оставалась проблема автоматизации трансфера данных. Следовательно, нужен был инструмент, в котором можно автоматизировать трансфер и прочие рутинные операции, выполняемые вручную.

Именно для решения задач автоматизации я стал изучать R, и за последние два года он стал моим основным рабочим инструментом. На самом деле R может закрыть и задачу визуализации, а возможности этого языка ограничиваются лишь вашей фантазией. В этой статье я расскажу, как с его помощью получить данные из API интерфейсов наиболее популярных рекламных площадок, т.к. именно это являлось главной задачей в агентстве интернет-маркетинга Netpeak.

Глоссарий — немного терминологии

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

Функция — сгруппированный набор команд, возвращающий какое-либо значение, функции в R. Как я уже писал выше, функции в R аналогичны функциям в MS Excel.

Аргументы — практически любая функция запрашивает на вход какие-то значения, на основе которых потом производит какие-то действия и вычисления. Все эти значения вы присваиваете аргументам функции. Например, вспомним функцию ВПР в Excel, ее синтаксис выглядит следующим образом:

=ВПР(искомое значение; диапазон для поиска значения; номер столбца в диапазоне с возвращаемым значением; [точное или приблизительное совпадение — указывается как 0/ЛОЖЬ или 1/ИСТИНА])

Все значения, которые вы указываете внутри скобок после имени функции — это и есть аргументы функции. Функция ВПР имеет 3 обязательных аргумента: искомое значение, диапазон для поиска значения, номер столбца в диапазоне с возвращаемым значением; и один необязательный аргумент — точное или приблизительное совпадение.

Оператор присваивания — чтобы присвоить какому-либо объекту какое-то значение, в языке R существует оператор присваивания «<-». Например, чтобы создать переменную X, которая будет содержать значение 10, необходимо выполнить следующую команду.

X <- 10

Вектор — в языке R представляет собой именованный одномерный массив, содержащий набор однотипных элементов (числовые, логические, либо текстовые значения — никакие сочетания не допускаются). Для создания векторов небольшой длины используется т.н. функция конкатенации c() (от «concatenate» — объединять, связывать). В качестве аргументов этой функции через запятую перечисляют объединяемые в вектор значения.

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

camp_name <- c(“CampName1”, ”CampName2”, “CampName3”, “CampName4”)

DataFrame — класс объектов в R, соответствующий привычным для нас таблицам. На самом деле это набор векторов одной длины, но именно так мы и представляем все таблицы, с которыми привыкли работать.

Пример встроенного в R дата фрейма mtcars. Данные были извлечены из журнала Motor Trend US 1974 года и включают расход топлива, 10 аспектов автомобильного дизайна и различных характеристик для 32 автомобилей (модели 1973-74):

Листинг примеров кода из статьи

В статье будут приведены примеры кода обращения к API Google AdWords и Яндекс.Директ на языке R. Все примеры вы можете копировать непосредственно из текста статьи или скачивать из репозитория на GitHub, перейдя по этой ссылке.

Установка языка R

Для усвоения изложенного в статье материала я рекомендую выполнять представленные примеры кода непосредственно на вашем ПК, поэтому для начала давайте установим R. ​

R является кроссплатформенным языком. Вы можете установить его как на Windows, так и на MacOS и Unix-подобные операционные системы. ​

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

Что такое пакеты в R

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

Пакет для R — это модуль, содержащий набор функций и наборов данных. Основным репозиторием хранения пакетов для R является CRAN, и на момент написания этого абзаца в CRAN было доступно 12148 пакетов. Помимо CRAN огромное количество пакетов пользователи выкладывают в открытый доступ на GitHub. Как правило, там можно найти наиболее актуальные версии пакетов от их разработчиков, и сейчас на GitHub уже 77 тысяч репозиториев на языке R.

Установка и подключения пакетов на языке R

Чтобы воспользоваться функциями или наборами данных из какого-либо пакета, его предварительно необходимо установить. Для установки пакета из CRAN достаточно воспользоваться функцией install.packages, которая имеет 1 обязательный аргумент — название пакета.

Давайте установим пакет devtools.

install.packages("devtools")

Пакет devtools содержит набор функций для разработки собственных функций на R, а также для установки пакетов из сторонних репозиториев, включая GitHub.

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

Чтобы установить пакет из GitHub в пакете devtools, есть функция install_github. Однако т.к. пакет devtools не входит в базовую комплектацию R, чтобы воспользоваться его функциями, необходимо предварительно подключить его к сессии R с помощью команды library.

#Подключаем пакет devtools
library(devtools)

#Устанавливаем пакет RAdwords
install_github(’jburkhardt/RAdwords’)

В данном случае функция install_github имеет также всего 1 обязательный аргумент — имя пользователя, автора репозитория на GitHub (https://github.com/jburkhardt) и название репозитория RAdwords (https://github.com/jburkhardt/RAdwords).

Получение подробной справки по работе с функциями пакета

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

Чтобы получить список функций пакета с описанием того, что каждая из функций делает, воспользуйтесь командой help и передайте в аргументе package название пакета, по которому хотите получить список функций. Например, чтобы получить справку по функциям пакета RAdwords, надо запустить следующую команду:

help(package = «RAdwords»)

В результате будет открыта html страница следующего содержания:

результат запуска команды help(package = "RAdwords")

Если вам необходимо получить справку по какой-то одной конкретной функции, то можно в help передать ее название. Например, для получения справки по функции doAuth подключите пакет RAdwords с помощью функции library и запустите help.

help("doAuth")

R пакеты для работы с рекламными системами

RAdwords — пакет, позволяющий работать с API Google AdWords

Ссылка на официальную документацию RAdwords

Репозиторий на GitHub

Автор: Johannes Burkhardt

Установка пакета: devtools::install_github(’jburkhardt/RAdwords’)

Принцип работы с API AdWords

Google AdWords имеет довольно широкий API интерфейс для загрузки данных из вашего рекламного аккаунта, состоящий из 49 отчетов. Возможно, поначалу будет довольно сложно определить, какой именно из этих отчетов вам может понадобиться. В официальной документации для облегчения поиска нужного отчета приведена такая таблица:

Схема для помощи в поиске нужных отчетов в AdWords API

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

Набор полей отчета Campaign Performance Report

Атрибуты — это поля, измерения или параметры, содержащие информацию о каких-либо настройках или константах, которые не изменяют группировку запрашиваемых данных. Например, такие настройки аккаунта, как валюта (поле AccountCurrencyCode), никак не поменяют количество строк, запрашиваемых из отчета «Campaign Performance Report».

Сегменты — также являются параметрами, но при этом меняют группировку запрашиваемых данных. Например, если запросить данные из отчета «Campaign Performance Report» с полем Date, которое является атрибутом, то запрашиваемые данные по эффективности кампаний будут сгруппированы по датам.

Метрики — количественные показатели, такие как клики, показы, общий объем потраченных средств и т.д.

С помощью пакета RAdwords вы можете обращаться к любому из этих отчетов и запрашивать доступные в отчете поля, не разбираясь с тонкостями формирования и отправки HTTP запросов к API сервису, а также различных нюансах работы самого API интерфейса.

Что требуется для работы с RAdwords

Для работы с пакетом RAdwords вам понадобится доступ к API Google AdWords. О том, как его получить, довольно подробно описано в справке.

Чтобы настроить доступ к API, вам потребуется идентификатор и секретный ключ клиента OAuth2. Под клиентом здесь подразумевается ваше клиентское приложение, а не клиентский аккаунт AdWords.

  1. Войдите в управляющий аккаунт и откройте страницу «Учетные данные» в Google Developers Console.
  2. В раскрывающемся меню проектов выберите «Создать проект». Затем укажите название проекта и нажмите кнопку «Создать».
  3. Выберите «Создать учетные данные», а затем — «Идентификатор клиента OAuth».
  4. Если система предложит указать название продукта, нажмите «Настроить окно запроса доступа», укажите запрашиваемую информацию и нажмите «Сохранить», чтобы вернуться к экрану «Учетные данные».
  5. В разделе «Тип приложения» выберите «Другие типы». Укажите название в появившемся поле.
  6. Нажмите кнопку «Создать». Появятся идентификатор и секретный ключ клиента OAuth2. Скопируйте и сохраните их. На следующем шаге их нужно будет добавить в файл конфигурации.
Клиент OAuth

Основные функции пакета RAdwords

На самом деле в RAdwords не так много функций. Вот список основных из них:

  • doAuth — аутентификация в API. Для ее прохождения вам потребуется токен разработчика AdWords, идентификатор и секретный ключ клиента, созданного в Google Console на предыдущем шаге.
  • reports — возвращает вектор доступных отчетов в API в ответ на запрос.
  • metrics — возвращает вектор полей, доступных в отчете, в ответ на запрос.
  • statement — подготовка запроса к API AdWords.
  • getData — отправка запроса и получение данных из API.

Пример кода для получения данных из Google AdWords с помощью RAdwords

						
#Подключение пакета
library(RAdwords)

#Аутентификация
adwords_auth <- doAuth()
account_id   <- "000-000-0000" #ID вашего рекламного аккаунта AdWords

#Подготовка запроса
#Берём данные за предыдущие 30 дней
#Функция format.Date преобзаует дату из стандартного формата 2017-01-01 в 20170101
body <- statement(select=c('Date',
                           'CampaignName',
                           'CampaignId',
                           'AccountCurrencyCode',
                           'Impressions',
                           'VideoViews',
                           'Clicks',
                           'Interactions',
                           'AllConversions',
                           'Cost'),
                  report="CAMPAIGN_PERFORMANCE_REPORT",
                  start=format.Date(Sys.Date() - 31, "%Y%m%d"),
                  end=format.Date(Sys.Date() - 1, "%Y%m%d"))

#Запрашиваем данные
AdwData <- getData(clientCustomerId = account_id,
                   google_auth = adwords_auth,
                   statement = body,
                   transformation = T)

						
					

Открыть пример кода на GitHub

Функция statement формирует тело запроса. В аргументе select вы в виде вектора передаете название всех запрашиваемых полей. В аргумент report название отчета, из которого запрашиваете данные. В аргументы start и end передаете отчетный период.

Важно: дату необходимо перевести в формат ГГГГММДД. По умолчанию формат даты в R — ГГГГ-ММ-ДД. Вы можете либо в виде строки передать нужные даты, либо преобразовать любую дату с помощью функции format.Date, как в моем примере выше.

Функция getData запрашивает в агрумент clientCustomerId номер рекламного аккаунта AdWords в формате 000-000-0000.

В начале скрипта мы создали переменную adwords_auth и передали в нее с помощью функции doAuth учетные данные, необходимые для доступа к API Google AdWords. В аргумент google_auth функции getData необходимо передать сохраненные ранее учетные данные.

В аргумент statement следует передавать тело запроса, созданное с помощью функции statement.

После выполнения приведенного выше кода в рабочем окружении будет создан объект AdwData, который будет содержать таблицу (Data frame) со всей запрошенной из API информацией.

Еще несколько примеров работы с RAdwords

ryandexdirect — пакет позволяющий работать с API Яндекс.Директ и Яндекс.Метрикой

Ссылка на официальную документацию ryandexdirect

Репозиторий на GitHub

Автор: Алексей Селезнев

Установка пакета на Windows: devtools::install_github("selesnow/ryandexdirect") Установка пакета на MacOS и Linux: devtools::install_github("selesnow/ryandexdirect«, subdir = «utf8»)

Принцип работы с API Яндекс.Директ

5 версия API Яндекс.Директ, в отличие от предыдущей, довольно сильно напоминает API Google AdWords при работе с получением статистики.

Для получения статистики в 5 версии API используется сервис Reports. С помощью данного сервиса вы так же, как и из API AdWords, можете запрашивать любые поля, доступные в одном из 7 отчетов.

Отчеты в сервисе Reports.

Тип отчета Описание
CAMPAIGN_PERFORMANCE_REPORT Статистика по кампаниям
ADGROUP_PERFORMANCE_REPORT Статистика по группам объявлений
AD_PERFORMANCE_REPORT Статистика по объявлениям
CRITERIA_PERFORMANCE_REPORT Статистика по условиям показа
CUSTOM_REPORT Статистика с произвольными группировками
SEARCH_QUERY_PERFORMANCE_REPORT Статистика по поисковым запросам

Наиболее общий тип отчета — CUSTOM_REPORT. Он не добавляет никаких дополнительных группировок.

Все поля отчетов разделены по типу:

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

Например, поле CampaignId для типа отчета CUSTOM_REPORT является сегментом — если его добавить в отчет, данные будут сгруппированы по кампаниям. А для типа отчета ADGROUP_PERFORMANCE_REPORT поле CampaignId является атрибутом — данные уже сгруппированы по AdGroupId, а идентификатор кампании является для каждой группы фиксированным значением.

Актуальный список всех доступных полей с их типами для каждого отчета можно найти в официальной справке Яндекс.Директ.

Некоторые поля нельзя одновременно запрашивать в рамках одного запроса:

  • Поля Date, Week, Month, Quarter, Year являются взаимоисключающими: только одно из них может присутствовать в отчете.
  • Поля CriterionType, CriteriaType, AudienceTargetId, DynamicTextAdTargetId, Keyword, SmartBannerFilterId являются взаимоисключающими: только одно из них можно использовать для фильтрации данных.
  • Поле ClickType несовместимо с полями Impressions, Ctr, AvgImpressionPosition.
  • Поле ImpressionShare несовместимо с полями AdFormat, AdId, Age, CarrierType, Gender, MobilePlatform, RlAdjustmentId, TargetingLocationId, TargetingLocationName.
  • Поля Criterion, CriterionId, CriterionType несовместимы с полями Criteria, CriteriaId, CriteriaType.

Основные функции пакета ryandexdirect

На момент написания этой статьи в текущей версии пакета ryandexdirect доступно 20 функций. Ниже я перечислю основные, которые использую для работы со статистикой:

  • yadirGetToken — получение токена доступа к API. Токен является обязательным для работы со всеми остальными функциями пакета, таким образом вы авторизуетесь для работы с API Директа.
  • yadirGetReport — получение статистики из сервиса Report.
  • yadirGetDictionary — получение справочной информации, например справочник регионов или курсов валют.
  • yadirGetLogsData — получение сырых данных из Logs API Яндекс.Метрики.
  • yadirGetMetrikaGAData — получение данных из API Яндекс.Метрики, совместимых с Google Analytics Core Reporting API (v3).

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

Для этого доступно 6 функций:

  • yadirStartAds — возобновить показы по объявлениям.
  • yadirStopAds — остановить показы по объявлениям.
  • yadirStartCampaigns — возобновить показы по рекламным кампаниям.
  • yadirStopCampaigns — остановить показы по рекламным кампаниям.
  • yadirStartKeyWords — возобновить показы по ключевым словам.
  • yadirStopKeyWords — остановить показы по ключевым словам.

Пример кода для получения статистики из Яндекс.Директ с помощью ryandexdirect.

Пример #1: Загрузка статистики по кампаниям в разрезе дат.

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

						
#Подключаем пакет
library("ryandexdirect")

#Получаем токен разработчика
tok <- yadirGetToken()

#Вводим переменную содержащую логин пользователя. Замените MYLOGIN на ваш логин в Яндексе
my_login <- “MYLOGIN”

#Запрашиваем статистику
data <- yadirGetReport(ReportType = "CAMPAIGN_PERFORMANCE_REPORT",
                       DateRangeType = "LAST_30_DAYS",
                       FieldNames = c("Date",
                                      "CampaignName",
                                      "CampaignId",
                                      "Impressions",
                                      "Clicks",
                                      "Cost"),
                       Login = my_login,
                       Token = tok )
						
					

Открыть пример кода на GitHub

Я думаю, приведенный код вполне понятен, но, на всякий случай, дам небольшие пояснения:

  • Изначально мы подключаем пакет с помощью команды library.
  • Далее получаем токен разработчика с помощью yadirGetToken и сохраняем его в объект tok. На самом деле не требуется каждый раз при обращении к API получать новый токен. Срок жизни одного токена — более 30 дней с момента последнего использования, поэтому получив его один раз, вы можете его использовать в скриптах в виде строки. Например, передать в объект tok значение полученного ранее токена вот так: tok <- «abcdefg1234567»
  • Запрашиваем данные из API функцией yadirGetReport.
  • Аргумент ReportType на входе требует название отчета, из которого вы будете запрашивать нужные вам поля. Поскольку мы планируем получить данные на уровне рекламных кампаний, наиболее подходящим отчетом для нас будет «CAMPAIGN_PERFORMANCE_REPORT».
  • В аргумент DateRangeType необходимо передать, как вы будете определять период. В нашем случае мы берем данные за последние 30 дней, но у вас есть довольно широкие возможности определения временного интервала:
    • TODAY — текущий день.
    • YESTERDAY — вчера.
    • LAST_3_DAYS, LAST_5_DAYS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_365_DAYS — указанное количество предыдущих дней, не включая текущий день.
    • THIS_WEEK_MON_TODAY — текущая неделя, начиная с понедельника, включая текущий день.
    • THIS_WEEK_SUN_TODAY — текущая неделя, начиная с воскресенья, включая текущий день.
    • LAST_WEEK — прошлая неделя с понедельника по воскресенье.
    • LAST_BUSINESS_WEEK — прошлая рабочая неделя с понедельника по пятницу.
    • LAST_WEEK_SUN_SAT — прошлая неделя с воскресенья по субботу.
    • THIS_MONTH — текущий календарный месяц.
    • LAST_MONTH — полный предыдущий календарный месяц.
    • ALL_TIME — вся доступная статистика, включая текущий день.
    • CUSTOM_DATE — произвольный период. При выборе этого значения необходимо указать даты начала и окончания периода в параметрах DateFrom и DateTo.
    • AUTO — период, за который статистика могла измениться. Период выбирается автоматически в зависимости от того, произошла ли в предыдущий день корректировка статистики. Подробнее см. в разделе «Как получить актуальную статистику».
  • В аргумент FieldNames необходимо передать вектор, содержащий названия запрашиваемых из отчета полей. В нашем случае мы перечисляем список запрашиваемых полей: Date, CampaignName, CampaignId, Impressions, Clicks, Cost. Список всех доступных полей можно найти в официальной справке.

После выполнения приведенного кода в рабочем окружении будет создан объект data, который будет представлять таблицу (Data frame), содержащую запрошенные из API данные.

Пример #2: Загрузка статистики из рекламного аккаунта в разрезе стран и регионов.

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

Дело в том, что поле LocationOfPresenceName, содержит максимально точное название географического места нахождения пользователя (села, города или области). И если мы, к примеру, хотим посмотреть данные в разрезе областей, а не городов, то необходимо загрузить справочник регионов и привести его к нужному виду с помощью рекурсивного сканирования справочника.

Выполним приведенный ниже код.

						
#Подключаем пакет
library("ryandexdirect")

#Получаем токен разработчика
tok <- yadirGetToken()

#Вводим переменную содержащую логин пользователя, замените MYLOGIN на ваш логин в Яндексе
my_login <- "MYLOGIN"

#Получаем географический справочник
geo_dict <- yadirGetDictionary(DictionaryName = "GeoRegions", Language = "en", login = my_login, token = tok )

#Добавляем поле с идентификатором страны
geo_dict$CountryID <- NA

#Определяем страну для каждого элемента справочника
#Запускаем цикл по каждому элементу справочника
for(gd in 1:nrow(geo_dict)){
  #Проверяем, если текущий элемент является страной то в поле ID страны устанавливаем ID этого же элемента, иначе устанавливаем ID родительского элемента
  if(geo_dict$GeoRegionType[gd] == "Country"){
    geo_dict$CountryID[gd] <- geo_dict$GeoRegionId[gd]
  }else{
    geo_dict$CountryID[gd] <- geo_dict$ParentId[gd]}

  #Проверяем тип родительского региона, если он ниже страны то присваиваем в ID страны ID региона который является родительским для родительского региона начальной строки, повторяем до тех пор пока не найдём страну
  while(geo_dict$GeoRegionType[geo_dict$GeoRegionId == geo_dict$CountryID[gd]] %in% c("Administrative area", "District", "City", "City district", "Village")){

    geo_dict$CountryID[gd] <- geo_dict$ParentId[geo_dict$GeoRegionId == geo_dict$CountryID[gd]]

  }
}


#Отделяем справочник областей
geo_dict <- merge(geo_dict, subset(geo_dict, select = c("GeoRegionId","GeoRegionName")),by.x = "CountryID", by.y = "GeoRegionId", all.x = T)
names(geo_dict) <- c("CountryID", "GeoRegionId", "ParentId", "GeoRegionType", "GeoRegionName", "CountryName")

#Добавляем поле с идентификатором области
geo_dict$AreaID <- NA

#Определяем область для каждого элемента справочника
#Запускаем цикл по каждому элементу справочника
for(gd in 1:nrow(geo_dict)){
  #Проверяем если текущий элемент является областью то в поле ID страны устанавливаем ID этого же элемента, иначе устанавливаем ID родительского элемента
  if(geo_dict$GeoRegionType[gd] == "Administrative area"){
    geo_dict$AreaID[gd] <- geo_dict$GeoRegionId[gd]
  }else{
    geo_dict$AreaID[gd] <- geo_dict$ParentId[gd]}

  #Проверяем тип родительского региона, если он ниже области то присваиваем в ID области ID региона который является родительским для родительского региона начальной строки, повторяем до тех пор пока не найдём область
  while(geo_dict$GeoRegionType[geo_dict$GeoRegionId == geo_dict$AreaID[gd]] %in% c("District", "City", "City district", "Village")){

    geo_dict$AreaID[gd] <- geo_dict$ParentId[geo_dict$GeoRegionId == geo_dict$AreaID[gd]]

  }
}

#Отделяем справочник областей
geo_dict <- merge(geo_dict, subset(geo_dict, select = c("GeoRegionId","GeoRegionName")),by.x = "AreaID", by.y = "GeoRegionId", all.x = T)
names(geo_dict) <- c("AreaID","CountryID", "GeoRegionId", "ParentId", "GeoRegionType", "GeoRegionName", "CountryName", "AreaName")

#Запрашиваем статистику из Report сервиса
stat <- yadirGetReport(ReportType = "CUSTOM_REPORT",
                       DateRangeType = "CUSTOM_DATE",
                       DateFrom = "2018-01-01",
                       DateTo = "2018-01-31",
                       FieldNames = c("LocationOfPresenceId",
                                      "Impressions",
                                      "Clicks",
                                      "Cost"),
                       FilterList = NULL,
                       IncludeVAT = "YES",
                       IncludeDiscount = "NO",
                       Login =my_login,
                       Token = tok)

#Соединяем данные статистики со справочником регионов
stat <- merge(stat, geo_dict, by.x = "LocationOfPresenceId", by.y = "GeoRegionId", all.x = T)
						
					

Открыть пример кода на GitHub

Первое, что мы делаем после подключения пакета, получения токена и объявления нужных нам переменных — это запрос географического справочника с помощью функции yadirGetDictionary.

Справочник, который возвращает API, содержит всего 4 поля:

  • GeoRegionId — идентификатор региона.
  • GeoRegionName — название региона.
  • GeoRegionType — тип региона: World, Continent, Region, Country, Administrative area, District, City, City district, Village.
  • ParentId — идентификатор вышестоящего региона.

Как я уже писал выше, в ответ на запрос API вернет статистику по максимально точному месту нахождения пользователя, согласно представленной в GeoRegionType иерархии. Это значит, что если пользователь, кликнувший по объявлению, находится в селе (Village — нижний уровень иерархии географического справочника), которое занесено в географический справочник, то данные по количеству кликов и потраченным средствам будут отнесены к ID именно этого села.

Таким образом вы получаете из API данные из разных географических иерархий, села, города, области, регионы, континенты и т.д.

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

Следующая часть кода находит для каждого элемента справочника административный регион и страну, в которую данный элемент входит.

В результате мы преобразуем полученный ранее справочник к следующему виду:

  • AreaID — ID административного округа, в который входит текущий элемент справочника.
  • CountryID — ID страны округа, в который входит текущий элемент справочника.
  • GeoRegionId — ID текущего элемента справочника.
  • ParentId — ID родительского элемента.
  • GeoRegionType — тип региона текущего элемента справочника.
  • CountryName — название страны, в которую входит текущий элемент справочника.
  • GeoRegionName — название региона текущего элемента справочника.
  • AreaName — название административного округа, в который входит текущий элемент справочника.

После того, как мы преобразовали справочник, запрашиваем статистику из рекламного аккаунта, сгруппированную по полю LocationOfPresenceId. С помощью функции merge объединяем данные статистики с данными из географического справочника по полям LocationOfPresenceId и GeoRegionId.

Используя аргумент all.x = T, мы говорим о том, что необходимо к таблице X (данные статистики) присоединить таблицу Y (географический справочник) с помощью левого внешнего соединения (LEFT JOIN). То есть мы берем все строки из таблицы статистики и присоединяем к ним нужные строки из географического справочника по ключу GeoRegionId.

Таким образом мы получили отчет по первичным показателям эффективности рекламных кампаний в разрезе стран и регионов.

Еще несколько примеров работы с ryandexdirect

Выводы

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

При использовании нужного пакета вам не придется неделями изучать документацию по работе с API интерфейсом какого-либо сервиса, потому что 90% работы за вас уже кто-то сделал. Вам остается лишь найти в нужном пакете пару функций, необходимых для выполнения вашей задачи, и изучить их аргументы.

Успехов вам в построении автоматизации и изучении языка R. Если остались вопросы или нужен совет, буду рад ответить вам в комментариях.