# Wordstat

# Проверка частоты фразы

Метод Frequency возвращает частоту фразы в Yandex Wordstat.

Чтобы получить частоту фразы, необходимо выполнить POST-запрос на адрес [https://moab-apis.ru/api/v1/wordstat/frequency](https://moab-apis.ru/api/v1/wordstat/frequency) с заголовком X-Api-Key и телом запроса в виде следующего JSON-объекта:

```json
{
  "query": "купить слона",
  "region": "225",
  "device": "All",
  "syntax": "Ws"
  "task_type": "Direct"
}
```

Опишем поля JSON-объекта подробнее:

- **query** – непосредственно запрос (искомая ключевая фраза)
- **region** – код региона Yandex. С основными кодами регионов вы можете ознакомиться, например, [здесь](https://yandex.ru/dev/xml/doc/ru/reference/regions). Если вам нужны дополнительные коды, которых нет в этом списке, вы можете воспользоваться поиском в справочнике регионов (см. соответствующий раздел данной документации). Коды можно указывать как в одиночку (225), так и через запятую (225, 213). Также можно указывать знак минус “-” перед кодом региона, чтобы исключить его из выдачи (225,-213)
- **device** – устройство. Возможные варианты значений: 
    - **All** – все устройства
    - **Desktop** – десктопные компьютеры
    - **Phone** – мобильные устройства
    - **Tablet** – планшеты
- **syntax** – синтаксис запроса. Возможные варианты значений: 
    - **None** – запрос передается “как есть”, можно использовать свой синтаксис
    - **WS** – запрос передается без кавычек, если передается в другом синтаксисе – будет автоматически преобразован в запрос без кавычек
    - **Quotes** – запрос передается в кавычках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках
    - **QuotesExclamationMark** – запрос передается в кавычках и с восклицательным знаком перед каждым словом, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и с восклицательным знаком перед каждым словом
    - **QuotesSquareBrackets** – запрос передается в кавычках и в квадратных скобках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и в квадратных скобках
    - **QuotesExclamationMarkSquareBrackets** – запрос передается в кавычках и с восклицательным знаком перед каждым словом и в квадратных скобках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и с восклицательным знаком перед каждым словом и в квадратных скобках
- **task\_type** - тип задачи 
    - **Regular** - обычный вордстат
    - **Direct** - вордстат из [Яндекс.Директа](https://direct.yandex.ru/registered/main.pl?checkboxes=1&cmd=wordstat&from_forecast=1&tm=&geo=0)

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

Если запрос выполнен успешно, в ответ вы получите HTTP-код 200 и JSON-ответ вида:

```json
{
  "frequency": 34032
}
```

Здесь:

- **frequency** – частота запроса с учетом указанного региона, устройства и синтаксиса

# Получение новых фраз

Метод Deep возвращает список запросов из Yandex Wordstat по исходному запросу.

Чтобы получить список запросов, необходимо выполнить POST-запрос на адрес [https://moab-apis.ru/api/v1/wordstat/deep](https://moab-apis.ru/api/v1/wordstat/deep) с заголовком X-Api-Key и телом запроса в виде следующего JSON-объекта:

```json
{
  "query": "купить слона",
  "region": "225",
  "device": "All",
  "task_type": "Direct"
}
```

Поля соответствуют полям, описанным в разделе Frequency. Синтаксис в методе Deep не используется – запросы всегда передаются “как есть”.

> Поле "**device**" игнорируется при использовании **task\_type="Direct"** - не поддерживается самим сервисом. Также при использовании **task\_type="Direct"** невозможно получить больше 500 фраз - сам сервис не отдает больше (в отличие от **"Regular"**, где можно получить 2000 фраз).

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

Если запрос выполнен успешно, в ответ вы получите HTTP-код 200 и JSON-ответ вида:

```json
{
  "associations": [
    {
      "frequency": "794630",
      "phrase": "3 цены"
    },
    {
      "frequency": "10529",
      "phrase": "магазин динамо"
    },
    ...
  ],
  "popular": [
    {
      "frequency": "34034",
      "phrase": "купи слона"
    },
    {
      "frequency": "5435",
      "phrase": "магазин купи слона"
    },
    ...
  ]
}
```

В ответе представлены JSON-массивы, в которых переданы следующие значения:

- **associations** – “похожие” запросы вордстат (то, что раньше называлось “правой колонкой”)
- **popular** – “популярные” запросы wordstat (то, что раньше называлось “левой колонкой”)

# Получение истории показов

Метод History возвращает историю запросов из Yandex Wordstat по исходному запросу.

Чтобы получить историю запросов, необходимо выполнить POST-запрос на адрес [https://moab-apis.ru/api/v1/wordstat/history](https://moab-apis.ru/api/v1/wordstat/history) с заголовком X-Api-Key и телом запроса в виде следующего JSON-объекта:

```json
{
  "query": "Купить",
  "region": "225",
  "device": "All",
  "grouping": "Month",
  "start_date": null,
  "end_date": null
}
```

Параметры **query**, **region** и **device** имеют такое же назначение, как и описанные в методе Frequency. Однако, здесь добавляется еще один параметр grouping, который отвечает за период группировки и может принимать значения:

- **Day** – группировка по дням
- **Week** – группировка по неделям
- **Month** – группировка по месяцам

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

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

- **start\_date** (Nullable) – дата начала периода (в формате YYYY-DD-MM)
- **end\_date** (Nullable) – дата окончания периода (в формате YYYY-DD-MM)

Если даты указать как null – вернутся все значения, возвращаемые Wordstat’ом по умолчанию.

К указанию дат применяются определенные требования:

- При указании группировки **Day**: Максимальный период: 60 дней. Минимальный период: 3 дня. Считаем от вчерашнего дня
- При указании группировки **Week**: Максимальный период: 7 лет с учетом календарной недели. Минимальный 3 календарные недели
- При указании группировки **Month**: Максимальный период: 7 лет с учетом полного календарного месяца. Минимальный 3 полных календарных месяца

Даты в группировках **Week** и **Month** необходимо указывать строго как начало/конец искомого периода

- для группировки **Week start\_date** должен быть всегда понедельником, **end\_date** – воскресеньем
- для группировки **Month start\_date** должен быть всегда первым числом месяца, **end\_date** – последним

При несоблюдении этих требований будет возвращена стандартная ошибка с пояснениями в поле **invalid\_data**.

Если запрос выполнен успешно, в ответ вы получите HTTP-код 200 и JSON-ответ вида:

```json
{
  "items": [
    {
      "date": "2025-07-01",
      "frequency": 163857055,
      "all_requests_percentage": 1.67
    },
    {
      "date": "2025-08-01",
      "frequency": 160182297,
      "all_requests_percentage": 1.66
    },
    {
      "date": "2025-09-01",
      "frequency": 156048613,
      "all_requests_percentage": 1.45
    }
  ]
}
```

В ответе возвращается массив **items**, который содержит в себе исторические данные частоты по запросу в выбранном периоде группировки. **frequency** в этом массиве означает абсолютную частоту, **all\_requests\_percentage** – относительную.