Wordstat

• Проверка частоты фразы
• Получение новых фраз
• Получение истории показов

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

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

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

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

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

• query – непосредственно запрос (искомая ключевая фраза)
• region – код региона Yandex. С основными кодами регионов вы можете ознакомиться, например, здесь. Если вам нужны дополнительные коды, которых нет в этом списке, вы можете воспользоваться поиском в справочнике регионов (см. соответствующий раздел данной документации). Коды можно указывать как в одиночку (225), так и через запятую (225, 213). Также можно указывать знак минус “-” перед кодом региона, чтобы исключить его из выдачи (225,-213)
  
• device – устройство. Возможные варианты значений:
  • All – все устройства
  • Desktop – десктопные компьютеры
  • Phone – мобильные устройства
  • Tablet – планшеты
    
• syntax – синтаксис запроса. Возможные варианты значений:
  • None – запрос передается “как есть”, можно использовать свой синтаксис
  • WS – запрос передается без кавычек, если передается в другом синтаксисе – будет автоматически преобразован в запрос без кавычек
  • Quotes – запрос передается в кавычках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках
  • QuotesExclamationMark – запрос передается в кавычках и с восклицательным знаком перед каждым словом, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и с восклицательным знаком перед каждым словом
  • QuotesSquareBrackets – запрос передается в кавычках и в квадратных скобках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и в квадратных скобках
  • QuotesExclamationMarkSquareBrackets – запрос передается в кавычках и с восклицательным знаком перед каждым словом и в квадратных скобках, если передается в другом синтаксисе – будет автоматически преобразован в запрос в кавычках и с восклицательным знаком перед каждым словом и в квадратных скобках
    
• task_type - тип задачи
  • Regular - обычный вордстат
  • Direct - вордстат из Яндекс.Директа

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

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

{
  "frequency": 34032
}

Здесь:

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

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

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

Чтобы получить список запросов, необходимо выполнить POST-запрос на адрес https://moab-apis.ru/api/v1/wordstat/deep с заголовком X-Api-Key и телом запроса в виде следующего 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-ответ вида:

{
  "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 с заголовком X-Api-Key и телом запроса в виде следующего 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-ответ вида:

{
  "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 – относительную.