# Moab-APIs.ru Документация к сервису парсинга MOAB APIs # Список версий API Версия 1 от 26.09.2025 - Начальная версия документации. Версия 2 от 07.10.2025 - Изменены форматы всех дат на YYYY-DD-MM (ISO 8601). - Добавлен универсальный формат сообщений об ошибках (см. далее в документации). - Добавлены группировки истории Wordstat по дням и неделям. - Добавлена возможность фильтрации (ограничения) истории Wordstat по датам. - Уменьшилось количество возможных кодов ответа HTTP – теперь соответствует фактическим кодам, которые возвращаются методами. - *Примечание: визуально добавилось "propertyName\*": "anything" во все запросы и ответы, по факту этого поля нет – это баг отображения Scalar после обновления до последней версии. Игнорируйте это поле.* Версия 3 от 12.10.2025 - Добавлена возможность парсинга данных вордстата [из Яндекс.Директ](https://direct.yandex.ru/registered/main.pl?checkboxes=1&cmd=wordstat&from_forecast=1&tm=&geo=0) (вместо обычного Wordstat, который в последнее время работает нестабильно). Работает только снятие частотности и парсинг вглубь, истории запросов в Яндекс.Директе нет. - Изменены некоторые запросы и ответы. Теперь **task\_type** означает не синтаксис, как было ранее, а тип задачи - **Regular** (обычный вордстат) или **Direct** (вордстат из Яндекс.Директа). Для указания синтаксиса теперь используется поле **syntax**. - Поле "**device**" не учитывается в вордстате Яндекс.Директ (не поддерживается самим сервисом). - Вместо поля **"is\_query\_invalid"** (что означало - ошибочный запрос) теперь выдается ошибка **422 Unprocessable Content** с телом ответа в виде JSON-ошибки. - Паразитное поле "propertyName\*": "anything" убрано из API после обновления. # Общие сведения API (Application Programming Interface) [moab-apis.ru](https://moab-apis.ru) – набор инструкций для взаимодействия с moab-apis.ru программно, используя скрипты на различных языках программирования. API moab-apis.ru подробно документирован с помощью популярной системы автодокументирования кода [https://scalar.com/](https://scalar.com/). Это позволяет на основе имеющейся документации понять, как устроен интерфейс API, а также, не выходя из браузера, протестировать взаимодействие с конечными точками интерфейса и получить исходный код для этого на популярных языках программирования. [![image.png](https://docs.moab.tools/uploads/images/gallery/2025-10/scaled-1680-/VHmimage.png)](https://docs.moab.tools/uploads/images/gallery/2025-10/VHmimage.png) Интерфейс Scalar API moab-apis.ru доступен по [этому адресу](https://moab-apis.ru/scalar/v1). Руководство по Scalar доступно [здесь](https://scalar.com/#introduction), мы не будем повторяться. Но опишем особенности взаимодействия с API moab-apis.ru для понимания того, как им пользоваться даже при наличии готового клиента и понимания работы со Scalar. Всё взаимодействие с API происходит в формате JSON, поэтому обязателен заголовок Content-Type: application/json (кроме тех случаев, когда в документации явно указан другой заголовок). Кодировка всех запросов и ответов – UTF-8. Все методы API должны вызываться со специальным заголовком X-Api-Key, который должен быть заполнен уникальным ключом API, характерным только для вашего аккаунта. Узнать его вы можете в службе поддержки moab-apis.ru. Этот заголовок является обязательным во всех запросах. Регистр символов API-ключа не имеет значения. Рекомендуется выполнять запросы в многопоточном режиме для ускорения. Поскольку API находится в состоянии beta и активно развивается - рекомендуется также использовать таймаут запросов 300 секунд и бесконечные попытки получить ответ в случае исчерпания таймаута. API moab-apis.ru подразделяется на несколько разделов: - Wordstat – методы работы с Yandex Wordstat. - YandexSerp – методы работы с выдачей Yandex \[пока не описано в этом руководстве\]. - Region – методы работы со справочником регионов. - GoogleSerp – методы работы с выдачей Google \[пока не описано в этом руководстве\]. - Finance – методы работы с финансами. - Models – описание моделей, используемых в API \[пока не описано в этом руководстве\]. В данном руководстве описаны минимально необходимые действия для получения данных с помощью API moab-apis.ru. Если вам необходимо выполнить какие-то дополнительные действия или получить дополнительную информацию из тех или иных методов API – пожалуйста, обратитесь в техподдержку moab-apis.ru, мы будем рады вам помочь! **API находится в состоянии beta и активно разрабатывается, вы можете повлиять на наличие и/или поведение тех или иных методов API.** # Поиск региона Разберем принцип взаимодействия с API на самом простом примере – поиске региона в справочнике регионов. Например, нам требуется найти регион Яндекса с названием “Москва”. Для поиска указанного региона по названию необходимо выполнить GET-запрос на конечную точку [https://moab-apis.ru/api/v1/region/yandex](https://docs.moab.tools/%D0%A0%D0%B0%D0%B7%D0%B1%D0%B5%D1%80%D0%B5%D0%BC%20%D0%BF%D1%80%D0%B8%D0%BD%D1%86%D0%B8%D0%BF%20%D0%B2%D0%B7%D0%B0%D0%B8%D0%BC%D0%BE%D0%B4%D0%B5%D0%B9%D1%81%D1%82%D0%B2%D0%B8%D1%8F%20%D1%81%20API%20%D0%BD%D0%B0%20%D1%81%D0%B0%D0%BC%D0%BE%D0%BC%20%D0%BF%D1%80%D0%BE%D1%81%D1%82%D0%BE%D0%BC%20%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D0%B5%20%E2%80%93%20%D0%BF%D0%BE%D0%B8%D1%81%D0%BA%D0%B5%20%D1%80%D0%B5%D0%B3%D0%B8%D0%BE%D0%BD%D0%B0%20%D0%B2%20%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B5%20%D1%80%D0%B5%D0%B3%D0%B8%D0%BE%D0%BD%D0%BE%D0%B2.%20%D0%9D%D0%B0%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80,%20%D0%BD%D0%B0%D0%BC%20%D1%82%D1%80%D0%B5%D0%B1%D1%83%D0%B5%D1%82%D1%81%D1%8F%20%D0%BD%D0%B0%D0%B9%D1%82%D0%B8%20%D1%80%D0%B5%D0%B3%D0%B8%D0%BE%D0%BD%20%D0%AF%D0%BD%D0%B4%D0%B5%D0%BA%D1%81%D0%B0%20%D1%81%20%D0%BD%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%D0%BC%20%E2%80%9C%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%E2%80%9D.%20%D0%94%D0%BB%D1%8F%20%D0%BF%D0%BE%D0%B8%D1%81%D0%BA%D0%B0%20%D1%83%D0%BA%D0%B0%D0%B7%D0%B0%D0%BD%D0%BD%D0%BE%D0%B3%D0%BE%20%D1%80%D0%B5%D0%B3%D0%B8%D0%BE%D0%BD%D0%B0%20%D0%BF%D0%BE%20%D0%BD%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D1%8E%20%D0%BD%D0%B5%D0%BE%D0%B1%D1%85%D0%BE%D0%B4%D0%B8%D0%BC%D0%BE%20%D0%B2%D1%8B%D0%BF%D0%BE%D0%BB%D0%BD%D0%B8%D1%82%D1%8C%20GET-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%20%D0%BD%D0%B0%20%D0%BA%D0%BE%D0%BD%D0%B5%D1%87%D0%BD%D1%83%D1%8E%20%D1%82%D0%BE%D1%87%D0%BA%D1%83%20https:/moab-apis.ru/api/v1/region/yandex.%20%D0%92%20GET-%D0%BF%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D0%B5%20query%20%D0%BD%D1%83%D0%B6%D0%BD%D0%BE%20%D1%83%D0%BA%D0%B0%D0%B7%D0%B0%D1%82%D1%8C%20%D0%BD%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%20(%D0%B8%D0%BB%D0%B8%20%D1%87%D0%B0%D1%81%D1%82%D1%8C%20%D0%BD%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F)%20%D1%80%D0%B5%D0%B3%D0%B8%D0%BE%D0%BD%D0%B0%20(%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80%20%D1%81%D0%B8%D0%BC%D0%B2%D0%BE%D0%BB%D0%BE%D0%B2%20%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D1%8F%20%D0%BD%D0%B5%20%D0%B8%D0%BC%D0%B5%D0%B5%D1%82),%20%D0%BD%D0%B0%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%20https:/moab-apis.ru/api/v1/region/yandex?query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0.%20%D0%92%20%D0%BE%D1%82%D0%BB%D0%B8%D1%87%D0%B8%D0%B5%20%D0%BE%D1%82%20%D0%BE%D1%81%D1%82%D0%B0%D0%BB%D1%8C%D0%BD%D1%8B%D1%85%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%BE%D0%B2,%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B%20%D0%BA%20%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B0%D0%BC%20%D0%BD%D0%B5%20%D1%82%D1%80%D0%B5%D0%B1%D1%83%D1%8E%D1%82%20%D0%BE%D0%B1%D1%8F%D0%B7%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE%20%D1%83%D0%BA%D0%B0%D0%B7%D0%B0%D0%BD%D0%B8%D1%8F%20%D0%B7%D0%B0%D0%B3%D0%BE%D0%BB%D0%BE%D0%B2%D0%BA%D0%B0%20X-Api-Key,%20%D0%BF%D0%BE%D1%8D%D1%82%D0%BE%D0%BC%D1%83%20%D0%BC%D0%BE%D0%B6%D0%BD%D0%BE%20%D0%BF%D1%80%D0%BE%D1%81%D1%82%D0%BE%20%D0%B2%D0%BF%D0%B8%D1%81%D0%B0%D1%82%D1%8C%20%D1%8D%D1%82%D0%BE%D1%82%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%20%D0%B2%20%D0%B0%D0%B4%D1%80%D0%B5%D1%81%D0%BD%D1%83%D1%8E%20%D1%81%D1%82%D1%80%D0%BE%D0%BA%D1%83%20%D0%B1%D1%80%D0%B0%D1%83%D0%B7%D0%B5%D1%80%D0%B0%20%D0%B8%20%D0%BF%D0%BE%D1%81%D0%BC%D0%BE%D1%82%D1%80%D0%B5%D1%82%D1%8C%20%D0%BD%D0%B0%20%D1%80%D0%B5%D0%B7%D1%83%D0%BB%D1%8C%D1%82%D0%B0%D1%82:). В GET-параметре query нужно указать название (или часть названия) региона (регистр символов значения не имеет), например [https://moab-apis.ru/api/v1/region/yandex?query=москва](https://moab-apis.ru/api/v1/region/yandex?query=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0). Запросы к справочнику регионов, как и остальные запросы, требуют наличия заголовка X-Api-Key, поэтому просто выполнить в браузере этот запрос не получится. В результате успешного выполнения запроса вы получите следующий результат: [![image.png](https://docs.moab.tools/uploads/images/gallery/2025-10/scaled-1680-/yYfimage.png)](https://docs.moab.tools/uploads/images/gallery/2025-10/yYfimage.png) Как видно из скриншота, вам возвращается JSON-массив со списком всех регионов, в названии которых было найдено слово “москва”. Нужный вам регион вы можете найти путем сравнения названий в вашем клиентском коде. Чем точнее вы укажете название региона – тем меньше результатов будет вам выдано. JSON-структура ответа обычным текстом выглядит вот так: ```json [   {     "name": "Аничково, Москва и Московская область, Щелковский район",     "code": "117175"   },   {     "name": "Барвиха, Москва и Московская область, Одинцовский район",     "code": "21652"   },   {     "name": "Быково, Москва и Московская область, Раменский район",     "code": "10718"   },   {     "name": "Железнодорожный, Москва и Московская область",     "code": "21622"   },   {     "name": "Заречье, Москва и Московская область, Одинцовский район",     "code": "21653"   },   {     "name": "Монино, Москва и Московская область, Щелковский район",     "code": "21636"   },   {     "name": "Москва",     "code": "213"   },   … ] ``` Найдя необходимый регион в справочнике, вы можете использовать значение поля code в дальнейших запросах к Yandex Wordstat и другим сервисам, которые связаны с Яндексом. В ответ на запрос вам может вернуться какой-то HTTP-код ответа из этого списка: [![image.png](https://docs.moab.tools/uploads/images/gallery/2025-10/scaled-1680-/Pwuimage.png)](https://docs.moab.tools/uploads/images/gallery/2025-10/Pwuimage.png) Все коды ответа, кроме 200, являются кодами ошибок. Каждый код ошибки означает ту или иную проблему, в таблице ниже смотрите описание возможных проблем.
Код ответаПотенциальная проблемаТекст ответа
200Проблем нетВ тексте ответа возвращается результат запроса.
400Неверно указаны параметры запроса.Проверьте параметры запроса на соответствие спецификации API.
401Не указан или указан неизвестный заголовок X-Api-Key. Пустой текст ответа. Не относится к справочникам.
404Фраза не найдена Соответствует ответу Wordstat “Нет подходящих запросов. Попробуйте изменить формулировку.” Возвращает стандартный формат ошибки (см. ниже)..
404Метод не найден Пустой текст ответа. Указана неверная конечная точка API.
422Неверно задан запрос Неверно указана проверяемая фраза - вордстат сам возвращает ошибку
Во всех случаях, когда возврат ошибки подразумевает возврат поясняющего сообщения – вам будет возвращена JSON-конструкция вида: ```json { "id": "fa18aecd-ac5c-443b-95a2-ef195949ecc7", "error_message": "NotFound", "instance": "/api/v1/region/check", "invalid_data": null } ``` Здесь: - **id** – уникальный идентификатор ошибки. Сообщите его вместе с сообщением об ошибке для облегчения сотрудникам техподдержки поиска конкретного случая возникновения ошибки. - **error\_message** – текстовое обозначение кода ошибки - **instance** – название конечной точки API, к которой было обращение, приведшее к ошибке - **invalid\_data** – массив строк, может содержать несколько строк, описывающих одну или несколько возникших ошибок. Nullable. # 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** – относительную. # Тарификация Тарификация запросов к API в сервисе [moab-apis.ru](http://moab-apis.ru) происходит позапросно за прошедший период. Расчет ведется согласно количеству выполненных к сервису запросов за период. Узнать количество запросов за период можно, вызвав метод [https://moab-apis.ru/api/v1/finance/statistics](https://moab-apis.ru/api/v1/finance/statistics) c параметрами в виде необходимого сервиса (например, Wordstat) и диапазона дат. Заголовок X-Api-Key является обязательным – по нему определяется, баланс какого пользователя необходимо отображать. Пример URL, по которому необходимо отправлять GET-запрос: [https://moab-apis.ru/api/v1/finance/statistics?service=Wordstat&startDate=2017-07-21&endDate=2026-07-21](https://moab-apis.ru/api/v1/finance/statistics?service=Wordstat&startDate=2017-07-21&endDate=2026-07-21) Даты необходимо указывать в формате YYYY-DD-MM (ISO 8601), например, 2025-07-21 В качестве ответа будет предоставлена JSON-структура: ```json {   "request_count": 0 } ``` В поле **request\_count** отобразится количество выполненных запросов за указанный период в указанном сервисе. Период указывается в днях, за начальную точку периода берется начало указанного в **start\_date** дня, за конечную точку периода – конец указанного в **end\_date** дня. # Примеры Примеры кода для интеграции API moab-apis.ru в ваши проекты на языке Python вы можете найти в [этом репозитории](https://github.com/moabtools/moab-apis). Мы будем поддерживать репозиторий в актуальном состоянии по мере развития API. В случае обнаружения каких-то проблем с примерами или интеграцией API в ваши проекты, вы можете обратиться в службу поддержки по адресу .