---
title: "Прогноз бюджета и отчёты сервиса WordStat"
author: "Alexey Seleznev"
output: rmarkdown::html_vignette
date: "`r Sys.Date()`"
vignette: >
  %\VignetteIndexEntry{ryandexdirect: Прогноз бюджета и отчёты сервиса WordStat}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(ryandexdirect)
```

# Отчёт WordStat
WordStat — это бесплатный сервис Яндекса, предназначенный для оценки пользовательского интереса к различным тематикам и подбора ключевых слов для SEO-оптимизации и контекстной рекламы.

Для того, что бы получить отчёты из данного сервиса с помощью пакета `ryandexdirect` необходимо использовать функцию `ydirGetWordStatReport()`.

Функция `ydirGetWordStatReport()` возвращает те же сведения, которые доступны в сервисе [Подбор слов](https://wordstat.yandex.ru/). Статистика рассчитывается за прошедший месяц.

## Видео урок
Помимо данной виньетки данная тема рассмотренна в видео уроке, который доступен по [ссылке](https://youtu.be/g9lwjsgAhyY).

## Аргументы функции ydirGetWordStatReport
* Phrases - Вектор ключевых фраз, по которым требуется получить статистику поисковых запросов (не более 10 фраз в кодировке UTF-8). Ключевые фразы могут содержать минус-фразы. Минус-фразу из нескольких слов следует заключить в скобки, например: `холодильник -морозильник -(морозильная камера) -ремонт`.
* GeoID - Вектор идентификаторов регионов. Позволяет получать статистику поисковых запросов, сделанных только в указанных регионах. Чтобы исключить регион, перед его идентификатором ставят минус, например [1,-219] — получить статистику для Москвы и Московской области, кроме Черноголовки. Статистика выдается суммарно по всем плюс-регионам, из которых исключены все минус-регионы. Получить справочник регионов можно с помощью функции `yadirGetDictionary()`

Остальные аргументы функции отвечают исключительно за авториацию, и с ними вы можете ознакомится в виньетке `vignette('yandex-direct-auth', "ryandexdirect")`.

## Пример загрузки отчёта по ключевым словам из Wordstat
В одном запросе вы можете получитьданные максимум по 10 ключевым фразам. 

Ключевые фразы могут содержать минус-фразы. Минус-фразу из нескольких слов следует заключить в скобки, например: `холодильник -морозильник -(морозильная камера) -ремонт`.

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

```{r}
s_ws_rep <- yadirGetWordStatReport(c('купить смартфон',
                                     'купить сотовый телефон',
                                     'купить мобильный',
                                     'samsung -(серого цвета)'),
                                   Login = "selesnow")
```

В ходе формирования и парсинга запроса в консоли вы можете наблюдать за прогрессом выполнения операции.
```
.Send report
.Report status: Pending
.Report status: Pending
.Report status: Pending
.Report status: Done
.Get report
.Parse report
.Delete report
Success!
Duration: 29 sec.
Request ID: 2685785695974693399
WordStat Report ID: 2016016472
Report SearchedAlso has 55 rows
Report SearchedWith has 900 rows
For get report data x[['ReportName']]
```

* Send report - Отчёт отправлен на API сервер
* Report status: Pending - Отчёт формируется на сервере API
* Report status: Done - Отчёт сформирован
* Get report - Получен отчёт от API сервера
* Parse report - Выполняется преобразование полученного от API результата в таблицы
* Delete report - Выполняется удаление отчёта с сервера API

В результате работы вы получите список, который состоит из двух таблиц: *SearchedWith* и *SearchedAlso*.

Обратиться к каждой из этих таблиц можно двумя способами:
```{r}
# Что искали с заданными ключевыми словами
s_ws_rep$SearchedWith
s_ws_rep[['SearchedWith']]

# Запросы, похожие на заданные ключевые слова
s_ws_rep$SearchedAlso
s_ws_rep[['SearchedAlso']]

```

Образение через `$` и по имени в двойных квадратных скобках равнозначны.

Если вам необходимо получить справочник проектов, и получить статистику по Москве, Санкт - Петербургу, Екатеринбург и Владивостоку, то изначально вам необходимо запросить справочник регионов с помощью функции `yadirGetDictionary()` и получить идентификаторы нужных регионов, а потом передать их в аргумент `GeoId`.
```{r}
library(dplyr)

# запрашиваем справочник регионов
regions <- yadirGetDictionary(Login = "selesnow")

# оставляем толлько нужные регионы
rep_regions <- regions %>%
                  filter(GeoRegionName %in% c("Москва",
                                              "Санкт-Петербург",
                                              "Екатеринбург",
                                              "Владивосток"))

# запрашиваем отчёт
reg_ws <- yadirGetWordStatReport(Phrases = c('купить смартфон -xiaomi', 
                                             'купить xiaomi'),
                                 GeoID   = rep_regions$GeoRegionId,
                                 Login   = "selesnow")
```

Так же вы можете указать минус регионы, например если вы хотите получить статистику по всей России без Москвы, Санкт - Петербуруа, Екатеринбурга и Владивостока. Для этого запросите справочник регионов, сначала получите идентификатор России (225), затем идентификаторы минус регионов, и перед идентификаторами минус регинов поставьте знак '-'. 

В приведённом ниже примере кода это реализуется с помощью функции `mutate()` из пакета `dplyr`.
```
library(dplyr)

# запрашиваем справочник регионов
regions <- yadirGetDictionary(Login = "selesnow")

# получаем идентификатор России
regions <- regions %>%
  filter(GeoRegionName %in% c("Россия"))

# Получаем идентификаторы минус регионов, и ставим перед ними минус
minus_regions <- regions %>%
                  filter(GeoRegionName %in% c("Москва",
                                              "Санкт-Петербург",
                                              "Екатеринбург",
                                              "Владивосток")) %>%
                  mutate(GeoRegionId = paste0("-", GeoRegionId))

# формируем запрос
reg_ws <- yadirGetWordStatReport(Phrases = c('купить смартфон -xiaomi', 
                                             'купить xiaomi'),
                                 GeoID   = c(regions$GeoRegionId, minus_regions$GeoRegionId),
                                 Login   = "selesnow")
```

# Получить прогноз показов, кликов и затрат
С помощью функции `yadirGetForecast()` вы можете получить прогнозируемые данные по расходам, показам и кликам указав интересующие вас ключевые фразы и регионы.

## Аргументы функции yadirGetForecast
* Phrases - Вектор ключевых фраз, для которых требуется получить прогноз (не более 100 фраз)
* GeoID - Вектор, содержащий идентификаторы регионов для составления прогноза. Если не задан, прогноз составляется по всем регионам.
* Currency - Валюта, в которой должны быть выражены цены клика и суммарные затраты в отчете. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.
* AuctionBids - Выводить ли в отчете результаты торгов — Yes/No или `TRUE` / `FALSE`. Если не задано, подразумевается No.

Пример кода для получения прогноза с использованием всех аргументов, минус слов и минус регионов с результататми торгов:
```{r}
library(dplyr)

# запрашиваем справочник регионов
regions <- yadirGetDictionary(Login = "selesnow")

# получаем идентификатор России
regions <- regions %>%
  filter(GeoRegionName %in% c("Россия"))

# получаем идентификатор минус регионов и помечаем их минусом
minus_regions <- regions %>%
  filter(GeoRegionName %in% c("Москва",
                              "Санкт-Петербург",
                              "Екатеринбург",
                              "Владивосток")) %>%
  mutate(GeoRegionId = paste0("-", GeoRegionId))

# запрашиваем прогноз с результататми торгов
forecast <- yadirGetForecast2(Phrases = c('купить смартфон -xiaomi', 
                                         'купить xiaomi',
                                         'самсунг -(серого цвета)'),
                             GeoID   = c(regions$GeoRegionId, minus_regions$GeoRegionId),
                             AuctionBids = 'Yes',
                             Login   = "selesnow")
```

В результате в объекте *forecast* будет список из двух таблиц:
* PhrasesForecast - Таблица прогноза в разреще всех указанных фраз
* CommonForecast - Общий суммарный прогноз

Обратится к таблицам можно по имени указав его через `$` или в двойных квадратных скобках.
```r
# прогноз в разрезе фраз
forecast$PhrasesForecast

# оющий прогнох
forecast[['CommonForecast']]
```

## Описание полей полученной таблицы прогнозов
Таблица *PhrasesForecast* сожержит следующие поля:

* PhrasesForecast - Ключевая фраза, для которой составлен прогноз.
* IsRubric - Признак того, что фраза является рубрикой Яндекс.Каталога.
* Min - Средневзвешенная цена клика в нижнем блоке на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* Max - Средневзвешенная цена клика на первом месте в нижнем блоке на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* PremiumMin - Средневзвешенная цена клика в спецразмещении на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* PremiumMax - Средневзвешенная цена клика на первом месте в спецразмещении на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* Shows - Возможное количество показов объявления по данной фразе за прошедший месяц.
* Clicks - Возможное количество кликов по объявлению в нижнем блоке (кроме первого места) за прошедший месяц.
* FirstPlaceClicks - Возможное количество кликов по объявлению на первом месте в нижнем блоке, за прошедший месяц.
* PremiumClicks - Возможное количество кликов по объявлению в спецразмещении за прошедший месяц.
* CTR - CTR при показе в нижнем блоке, в процентах. Рассчитывается по формуле: `Clicks/Shows * 100`
* FirstPlaceCTR - CTR при показе на первом месте в нижнем блоке. Рассчитывается по формуле: `FirstPlaceClicks/Shows * 100`
* Currency - Валюта, в которой выражены цены клика и суммарные затраты в отчете. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.
* Position - Позиция показа: *Pmn*, где: m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов); 
n — номер позиции в рамках блока. Например, P12 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов.
* Bid - Минимальная ставка за указанную позицию (в валюте, указанной в параметре `Currency`). Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* Price - Списываемая цена для указанной позиции (в валюте, указанной в параметре `Currency`). Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.

Таблица *CommonForecast* сожержит следующие поля:

* Geo - Список регионов, которые указаны при формировании отчета 
* Min - Средневзвешенная цена клика в нижнем блоке на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* Max - Средневзвешенная цена клика на первом месте в нижнем блоке на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* PremiumMin - Средневзвешенная цена клика в спецразмещении на момент составления прогноза. Значение конвертируется в валюту, указанную в параметре `Currency`, и округляется вверх с точностью до шага торгов в этой валюте.
* Shows - Возможное количество показов объявления по данной фразе за прошедший месяц.
* Clicks - Возможное количество кликов по объявлению в нижнем блоке (кроме первого места) за прошедший месяц.
* FirstPlaceClicks - Возможное количество кликов по объявлению на первом месте в нижнем блоке, за прошедший месяц.
* PremiumClicks - Возможное количество кликов по объявлению в спецразмещении за прошедший месяц.
