yamarketR - пакет для работы
с Партнёрским API Яндекс.Маркета
на языке R

Краткое описание

Данный пакет предназначен для получения данных из Яндекс.Маркета с помощью языка R.

Оглавление:

На очереди работа над функциями:

Функции пакета постепенно будут добавляться и расширяться в описании будет указаны статус разработки и планируемые изменения.

Автор пакета

Павел Мрыкин,
Руководитель отдела автоматизации и аналитики MediaGuru
email: mrykin@mediaguru.ru
skype: mrykin.pavel
facebook: facebook.com/mrykin.pavel
blog: www.mediaguru.ru/blog/

Установка пакета yamarketR

Установка пакета осуществляется из репозитория GitHub, для этого сначала требуется установить и подключить пакет devtools.

install.packages("devtools")
library(devtools)

После чего можно устанавливать пакет yamarketR.

install_github('mrykin/yamarketr')

Авторизация в API Яндекс Маркет

Вы можете в любой момент пройти аутентификацию в API Яндекс Маркет, однако это не обязательно, т.к. при запуске любой функции пакета, которая требует аутентификации будет запущен поиск файла с токеном доступа. Если файл не будет найден, то автоматически будет запущен процесс авторизации и запроса токена.

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

Создание папки

# Задаём адрес директории (папки) для токенов
path <- "C:/Tokens/yamarketR"
# Создаём директорию если её нет
dir.create(path, recursive=TRUE)

Теперь перед началом работы с функциями пакета необходимо объявить созданную папку “рабочей”, это позволит избежать необходимости повторно проходить авторизацию

Задать “рабочую” папку

Чтобы объявить папку “рабочей” - выполните функцию:

# Устанавливаем рабочую директорию
setwd("C:/Tokens/yamarketR")

Пример кода для прохождения авторизации

Если вы всё же хотите заранее пройти аутентификацию - выполните следующую функцию:

yamarketrAuth(Login = "Ваш логин в Яндексе", NewUser = FALSE, TokenPath = "путь к папке для сохранения токена")

Обновление токена

При каждом обращении к API проверяется количество дней до того как используемый токен станет просроченным, если остаётся менее 30 дней токен автоматически будет обновлён, и файл с учётными данными перезаписан.

Аргументы функции yamarketrAuth

Аргументы, общие для всех функций

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

Функции пакета

Загрузка списка кампаний (магазинов)

yamarketrGetCampaigns(Login = NULL, TokenPath = getwd())

Данная функция возвращает data.frame со списком всех кампаний доступных в аккаунте которому был выдан токен для доступа к API.

Структура data.frame, возвращаемого функцией yamarketrGetCampaigns:

ПолеТип данныхОписание
id int Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию.
domain chr URL-адрес кампании
state factor Статус магазина

Возможные значения:

  • включен.
  • выключен.
  • включается.
  • выключается.
stateReasons chr Список причин, объясняющих статус магазина.

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

  • выключен.
  • выключается.

Код причины.

Возможные значения:

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

    Параметр выводится только для формата XML и является атрибутом параметра reason. Для формата JSON выводится код причины в виде числа.

Загрузка текущего баланса магазинов

yamarketrGetBalance(Campaigns = NULL, Login = NULL, TokenPath = getwd())

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

Данная функция возвращает data.frame со списком всех кампаний доступных в аккаунте которому был выдан токен для доступа к API.

Структура data.frame, возвращаемого функцией yamarketrGetCampaigns:

ПолеТип данныхОписание
id int Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию.
balance num Текущий баланс магазина.

Все расчеты производятся в условных единицах (у. е.). В Маркете установлен постоянный курс, который составляет:

  • для России — 30 рублей (включая НДС);
  • для иностранных партнеров — 0,41 доллара.

    Подробнее по ссылке.

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).

Возможные значения:

  • поиск Яндекс.Маркета.
  • карточки товаров.

    Примечание. Значение не выводится, если во входных данных задан параметр model = 1.

  • Яндекс.Маркет, кроме карточек товаров.
  • поиск Яндекса, Яндекс.Картинки, сторонние сайты и сервисы.

    Если во входных данных указан параметр model = 1, дополнительные значения идентификатора места размещения непосредственно на карточке товара:

  • предложение по умолчанию.
  • блок «Топ-6».
  • остальные места на карточке.

  • иное - выводится, когда ни одна из других групп не подходит

    Если группировка по местам размещения не задана в запросе, значение параметра равно 0.
clicks int Количество кликов.

Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy).
spending num Расход по кликам в условных единицах с учетом НДС.

Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy).
shows int Количество показов предложения.

Выводится за день, неделю или месяц (в зависимости от значения параметра fetchBy).

Аргументы:

Загрузка списка логинов, прикреплённых к кампании (магазину)

yamarketrGetLogins(Campaigns, howmuch = NULL, Login = NULL, TokenPath = getwd())

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

Данная функция возвращает список логинов, которые прикреплены к выбранным магазинам. Может использоваться для группировки магазинов одного клиента.

Структура data.frame, возвращаемого функцией yamarketrGetLogins:

Поле Тип данных Описание
id int Идентификатор кампании. В интерфейсе он выводится в формате 11-******. В API же используется часть после дефиса. Количество знаков после дефиса может отличаться и зависит от того, как давно вы зарегистрировали кампанию.
logins chr логин или список логинов, можно регулировать кол-во выводимых логинов с помощью параметра howmuch

Атрибуты:

Загрузка информации об ошибках магазинов

yamarketrGetTickets(Campaigns, actualType = NULL, Login = NULL, TokenPath = getwd())

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

Данная функция возвращает данные о текущих ошибках магазина, выявленных службой контроля качества Яндекс.Маркета.

Структура 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 Статус ошибки.

Возможные значения:

  • 0 — ошибка выставлена.
  • 1 — магазин исправил ошибку.
orderId chr Идентификатор заказа на сайте магазина.

Присутствует в выходных данных, если параметр checkMethod - проверка с помощью добавления товара в корзину на сайте магазина.

Атрибуты:

Возможные значения: 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" # Разбивка по месяцам.
				   )