Данный пакет предназначен для получения данных из Яндекс.Маркета с помощью языка R.
- Установка пакета
- Авторизация в API Яндекс Маркет
- Функции пакета:
- Примеры работы с пакетом
На очереди работа над функциями:
- Расход по предложениям
- Параметры кампании
- Точки продаж
- Список предложений для модели (конкурентная аналитика в карточках)
Функции пакета постепенно будут добавляться и расширяться в описании будет указаны статус разработки и планируемые изменения.
Павел Мрыкин,
Руководитель отдела автоматизации и аналитики MediaGuru
email: mrykin@mediaguru.ru
skype: mrykin.pavel
facebook: facebook.com/mrykin.pavel
blog: www.mediaguru.ru/blog/
Установка пакета осуществляется из репозитория GitHub, для этого сначала требуется установить и подключить пакет devtools.
install.packages("devtools")
library(devtools)После чего можно устанавливать пакет yamarketR.
install_github('mrykin/yamarketr')Вы можете в любой момент пройти аутентификацию в API Яндекс Маркет, однако это не обязательно, т.к. при запуске любой функции пакета, которая требует аутентификации будет запущен поиск файла с токеном доступа. Если файл не будет найден, то автоматически будет запущен процесс авторизации и запроса токена.
Перед выполнением аутентификации рекомендую заранее создать папку для сохранения токенов и далее объявлять её рабочей директорией перед запуском функций пакета.
# Задаём адрес директории (папки) для токенов
path <- "C:/Tokens/yamarketR"
# Создаём директорию если её нет
dir.create(path, recursive=TRUE)Теперь перед началом работы с функциями пакета необходимо объявить созданную папку "рабочей", это позволит избежать необходимости повторно проходить авторизацию
Чтобы объявить папку "рабочей" - выполните функцию:
# Устанавливаем рабочую директорию
setwd("C:/Tokens/yamarketR")Если вы всё же хотите заранее пройти аутентификацию - выполните следующую функцию:
yamarketrAuth(Login = "Ваш логин в Яндексе", NewUser = FALSE, TokenPath = "путь к папке для сохранения токена")При каждом обращении к API проверяется количество дней до того как используемый токен станет просроченным, если остаётся менее 30 дней токен автоматически будет обновлён, и файл с учётными данными перезаписан.
Аргументы функции yamarketrAuth
- Login - имя пользователя или электронный адрес на Яндексе, с которого есть доступ к нужному вам рекламному аккаунту
- NewUser - логическое выражаение TRUE или FALSE, признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если вы хотите переключиться на другой аккаунт. По умолчанию установлено значение FALSE.
- TokenPath - путь к папке, в которой будут сохраняться учётные данные, по умолчанию это рабочая директория, но можно указывать любой путь, как абсолютный например "C:/Tokens/yamarketR", так и относительный "tokens", при использовании относительного пути в рабочей директории будет создана папка с установленным вами названием, и в неё будут сохраняться файлы с расширением .RData в которых хранятся учётные данные.
Во всех функции пакета существуют общие аргументы, в дальнейшем эти аргументы рассматриваться в описании функций не будут.
- Campaigns - data.frame, полученный в результате выполнения функции yamarketGetCampaigns со списком всех магазинов аккаунта, ID конкретного магазина или вектор, содержащий ID нескольких магазинов, для которых необходимо получить данные.
- Login - Логин яндекса, под которым есть доступ к нужным магазинам. В этот вектор необходимо указывать логин в случае если необходимо подключаться к разным аккаунтам. В противном случае при каждом запросе к новому аккаунту - токен будет перезатираться. При указании логина в рабочей директории будет создан отдельный файл под каждый логин, в котором будут хранится нужные для работы учётные данные.
- TokenPath - Путь к папке в которой хранятся все файлы с учётными данными, по умолчанию все функции пакета пытаются найти нужный файл с хранящимися учётными данными в текущей рабочей директории, но вы можете указывать абсолютный или условный путь к совершенно любой папке на вашем ПК, в которой вы хотите хранить все учётные данные ваших аккаунтов Яндекс Директ. Пример условного пути TokenPath = "market_token", в таком случае в рабочей директории будет создана папка market_token в которую и будут сохраняться все учётные данные, указав этот путь во всех функциях пакета вам не понадобится повторно запрашивать токены.
Данная функция возвращает data.frame со списком всех кампаний доступных в аккаунте которому был выдан токен для доступа к API.
Структура data.frame, возвращаемого функцией yamarketrGetCampaigns:
| Поле | Тип данных | Описание |
| id | int | Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию. |
| domain | chr | URL-адрес кампании |
| state | factor | Статус магазина
Возможные значения:
|
| stateReasons | chr | Список причин, объясняющих статус магазина.
Выводится, если параметр state имеет значения:
Код причины. Возможные значения:
|
Ссылка на официальную документацию.
Данная функция возвращает data.frame со списком всех кампаний доступных в аккаунте которому был выдан токен для доступа к API.
Структура data.frame, возвращаемого функцией yamarketrGetCampaigns:
| Поле | Тип данных | Описание |
| id | int | Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию. |
| balance | num | Текущий баланс магазина.
Все расчеты производятся в условных единицах (у. е.). В Маркете установлен постоянный курс, который составляет:
|
| daysLeft | int | Прогнозируемое количество дней, оставшихся до полного израсходования средств. |
| recommendedPayment | num | Рекомендованная сумма платежа, в условных единицах. |
yamarketrGetCosts(Campaigns, fromDate = format(Sys.Date()-8, "%d-%m-%Y"), toDate = format(Sys.Date()-1, "%d-%m-%Y"), Login = NULL, TokenPath = getwd(), places = 0, model = 0, fetchBy = "daily")
Ссылка на официальную документацию.
Данная функция возвращает data.frame со расходами магазинов, указанных в переменной Campaigns за последние 7 дней.
Структура data.frame, возвращаемого функцией yamarketrGetCosts:
| Поле | Тип данных | Описание |
| date | int | Дата, за которую был зафиксирован расход |
| id | int | Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию. |
| placeGroup | int | Места размещения при заданной в запросе группировке по местам размещения (параметр входных данных places=1).
Возможные значения:
|
| clicks | int | Количество кликов.
Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy). |
| spending | num | Расход по кликам в условных единицах с учетом НДС.
Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy). |
| shows | int | Количество показов предложения.
Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy). |
Аргументы:
-
fromDate, toDate - начальная и конечная даты отчётного периода, по умолчанию последние 7 дней.
Формат: ДД-ММ-ГГГ ("15-03-2018")
-
places - Признак группировки по местам размещения:
1 — группировать.
0 — не группировать.
По умолчанию места размещения не группируются.
-
model - подробная информация о месте размещения предложения на карточке модели.
Ограничение. Значение model работает, только если во входных данных задан параметр places со значением: 1
-
fetchBy = "daily" - признак группировки по дням, неделям, месяцам ("daily", "weekly", "monthly")
Ссылка на официальную документацию.
Данная функция возвращает список логинов, которые прикреплены к выбранным магазинам. Может использоваться для группировки магазинов одного клиента.
Структура data.frame, возвращаемого функцией yamarketrGetLogins:
| Поле | Тип данных | Описание |
| id | int | Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию. |
| logins | chr | логин или список логинов, можно регулировать кол-во выводимых логинов с помощью параметра howmuch |
Атрибуты:
-
howmuch - атрибут определяет количество логинов, которые нужно вывести.
По умолчанию - возвращаются все логины у которых есть доступ к магазину.
Ограничение задаётся с помощью чисел 1, 2, 3 и т.д.
Ссылка на официальную документацию.
Данная функция возвращает данные о текущих ошибках магазина, выявленных службой контроля качества Яндекс.Маркета.
Структура data.frame, возвращаемого функцией yamarketrGetTickets:
| Поле | Тип данных | Описание |
| id | chr | Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию. |
| ticketId | int | Идентификатор тикета на ошибку в службе контроля качества. |
| offerURL | chr | URL-адрес предложения с ошибкой на сайте магазина. |
| errorText | factor | Текстовое описание ошибки.
Возможные значения приведены в описании параметра error-code в официальной справке. |
| errorCode | factor | Код ошибки магазина. |
| errorFoundTime | PISIXct | Дата и время выявления ошибки. |
| feedTime | PISIXct | Дата и время загрузки прайс-листа. |
| checkMethod | factor |
Тип проверки магазина.
Возможные значения:
|
| status | factor | Статус ошибки.
Возможные значения:
|
| orderId | chr | Идентификатор заказа на сайте магазина.
Присутствует в выходных данных, если параметр checkMethod - проверка с помощью добавления товара в корзину на сайте магазина. |
Атрибуты:
-
actualType - Фильтрация актуальных ошибок магазина.
Возможные значения:
0 — актуальные ошибки (все ошибки, выявленные за последние 30 дней);
1 — архивные ошибки (все ошибки, выявленные более 30, но менее 90 дней назад).
# Подключаем пакет
library(yamarketr)
# Получаем список магазинов
campaigns <- yamarketrGetCampaigns(Login = "login", NewUser = TRUE)
# Получаем баланс по магазинам
balance <- yamarketrGetBalance(campaigns, Login = "login")# Подключаем пакет
library(yamarketr)
# Получаем список магазинов
campaigns <- yamarketrGetCampaigns(Login = "login", # Ваш логин в Яндексе
NewUser = FALSE # Указание типа пользователя для авторизации
)
# Получаем расходы по магазинам за последние 7 дней, не включая сегодняшний, по дням, без разбивки по местам размещения
balance7daysAgo <- yamarketrGetCosts(campaigns, # список магазинов, полученный на предыдущем шаге
Login = "login" # Ваш логин на Яндексе
)
# Получаем расходы по магазинам с 1 января до 30 сентября, по месяцам, с разбивкой по местам размещения
balancePlaces <- yamarketrGetCosts(campaigns, # список магазинов, полученный на предыдущем шаге
Login = "login", # Ваш логин на Яндексе
dateFrom="01-01-2018", # Начальная дата отчётного периода
dateFrom="30-09-2018", # Конечная дата отчётного периода
places = 1, # Указание разбивки по местам размещения
model = 1, # Указание подробной разбивки размещения в карточке модели
fetchBy = "monthly" # Разбивка по месяцам.
)