Moab-APIs.ru

Документация к сервису парсинга MOAB APIs

Список версий API

Версия 1 от 26.09.2025 

Версия 2 от 07.10.2025 

Версия 3 от 12.10.2025

Общие сведения

API (Application Programming Interface) moab-apis.ru – набор инструкций для взаимодействия с moab-apis.ru программно, используя скрипты на различных языках программирования. API moab-apis.ru подробно документирован с помощью популярной системы автодокументирования кода https://scalar.com/. Это позволяет на основе имеющейся документации понять, как устроен интерфейс API, а также, не выходя из браузера, протестировать взаимодействие с конечными точками интерфейса и получить исходный код для этого на популярных языках программирования. 

image.png

Интерфейс Scalar API moab-apis.ru доступен по этому адресу. 

Руководство по Scalar доступно здесь, мы не будем повторяться. Но опишем особенности взаимодействия с 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 подразделяется на несколько разделов:

В данном руководстве описаны минимально необходимые действия для получения данных с помощью API moab-apis.ru. Если вам необходимо выполнить какие-то дополнительные действия или получить дополнительную информацию из тех или иных методов API – пожалуйста, обратитесь в техподдержку moab-apis.ru, мы будем рады вам помочь! API находится в состоянии beta и активно разрабатывается, вы можете повлиять на наличие и/или поведение тех или иных методов API.

Поиск региона

Разберем принцип взаимодействия с API на самом простом примере – поиске региона в справочнике регионов. Например, нам требуется найти регион Яндекса с названием “Москва”. Для поиска указанного региона по названию необходимо выполнить GET-запрос на конечную точку https://moab-apis.ru/api/v1/region/yandex. В GET-параметре query нужно указать название (или часть названия) региона (регистр символов значения не имеет), например https://moab-apis.ru/api/v1/region/yandex?query=москва. Запросы к справочнику регионов, как и остальные запросы, требуют наличия заголовка X-Api-Key, поэтому просто выполнить в браузере этот запрос не получится. В результате успешного выполнения запроса вы получите следующий результат:

image.png

Как видно из скриншота, вам возвращается 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

Все коды ответа, кроме 200, являются кодами ошибок. Каждый код ошибки означает ту или иную проблему, в таблице ниже смотрите описание возможных проблем.

Код ответа Потенциальная проблема Текст ответа
200 Проблем нет

В тексте ответа возвращается результат запроса.
400 Неверно указаны параметры запроса.

Проверьте параметры запроса на соответствие спецификации API.
401

Не указан или указан неизвестный заголовок X-Api-Key.

Пустой текст ответа. Не относится к справочникам.
404

Фраза не найдена

Соответствует ответу Wordstat “Нет подходящих запросов. Попробуйте изменить формулировку.” Возвращает стандартный формат ошибки (см. ниже)..
404

Метод не найден

Пустой текст ответа. Указана неверная конечная точка API.
422

Неверно задан запрос

Неверно указана проверяемая фраза - вордстат сам возвращает ошибку

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

{
  "id": "fa18aecd-ac5c-443b-95a2-ef195949ecc7",
  "error_message": "NotFound",
  "instance": "/api/v1/region/check",
  "invalid_data": null
}

Здесь:

Wordstat

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-объекта подробнее:

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

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

{
  "frequency": 34032
}

Здесь:

Wordstat

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

Метод 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-массивы, в которых переданы следующие значения:

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, который отвечает за период группировки и может принимать значения:

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

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

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

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

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

При несоблюдении этих требований будет возвращена стандартная ошибка с пояснениями в поле 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 – относительную.

Тарификация

Тарификация запросов к API в сервисе moab-apis.ru происходит позапросно за прошедший период. Расчет ведется согласно количеству выполненных к сервису запросов за период. Узнать количество запросов за период можно, вызвав метод 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

Даты необходимо указывать в формате YYYY-DD-MM (ISO 8601), например, 2025-07-21

В качестве ответа будет предоставлена JSON-структура:

{
  "request_count": 0
}

В поле request_count отобразится количество выполненных запросов за указанный период в указанном сервисе. Период указывается в днях, за начальную точку периода берется начало указанного в start_date дня, за конечную точку периода – конец указанного в end_date дня.

 

Примеры

Примеры кода для интеграции API moab-apis.ru в ваши проекты на языке Python вы можете найти в этом репозитории. Мы будем поддерживать репозиторий в актуальном состоянии по мере развития API. В случае обнаружения каких-то проблем с примерами или интеграцией API в ваши проекты, вы можете обратиться в службу поддержки по адресу support@moab.pro.