Яндекс Search API версии 2, через который работаем мы, имеет два режима: синхронный и асинхронный. Синхронный режим похож на 1ю версию Яндекс Search API, с которой работало большинство программ до 01.03.2025 года. Далее речь идёт про 2ю версию Яндекс Search API, которую мы используем на данный момент.

У нас реализована работа в 2х режимах: гибридный и отложенный.
 

Гибридный режим
 

Этот режим создан для совместимости с программами, работающими с первой версией Яндекс Search API. В этом режиме формат общения - XML. HTML вы можете получить только если запросили формат выдачи HTML, но даже в этом случае, ошибки вы будете получать в формате XML.

Пример запроса: http://xmlriver.com/yandex/xml?user=[user_id]&key=[key]&query=запрос

Формат ошибки:

<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
   <response date="20120928T103130">
      <error code="15">Искомая комбинация слов нигде не встречается</error>
   </response>
</yandexsearch>

Этот режим реализован так:

• Вы отправляете нам запрос, мы его фиксируем;
• Мы отправляем запрос в Яндекс и сами следим за получением ответа, пока вы ожидаете ответ от нас (таймаут нашего ответа - до 10 секунд);
• Если в течение 10 секунд мы не смогли получить ответ от Яндекса, мы выдаём ошибку 500. Это сделано для максимальной совместимости с программами сбора. При этом необходимо делать перезапрос, желательно, не раньше, чем через 5-10 секунд;
• Если по вашему запросу было выдано 4 подряд ошибки 500, последующие разы будет выдана ошибка 202. Это следует учитывать при написании ПО для сбора. При ошибке 202 некоторые программы перестанут делать перезапрос и пропустят эту задачу до повторного запуска сбора.
• Получить ответ можно в течение 3х часов после отправки запроса к нам, если ответ не был получен ранее. Спустя 3 часа незабранный результат запроса удаляется. Если вы пришлёте тот же запрос к нам, то будет выполнен новый запрос к Яндексу. Тарифицируются только запросы, отправленные в Яндекс.
   

Отложенный режим
 

В этом режиме формат ответа всегда - JSON, и он повторяет форматы ответа Яндекса. Для работы в этом режиме вам необходимо к запросу добавлять параметр delayed=1.

Пример запроса: http://xmlriver.com/yandex/xml?user=[user_id]&key=[key]&query=запрос&delayed=1

В ответ вы получите идентификатор (ID) запроса от Яндекса в таком формате:

{
    "id": "sprg87pflgn913efphg9",
    "description": "WEB search async",
    "createdAt": "2025-04-11T09:58:53Z",
    "modifiedAt": "2025-04-11T09:58:53Z"
}

Далее, вам необходимо отправлять запросы на получение результата по этому ID с интервалом не менее 10 секунд! При попытке получить ответ раньше, вы получите ошибку 203.

Пример запроса: http://xmlriver.com/yandex/xml?req_id=sprg87pflgn913efphg9

Результат в формате:

{
 "done": true,
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
  "rawData": "<тело_XML_ответа_в_кодировке_Base64>"
 },
 "id": "sprg87pflgn913efphg9",
 "description": "WEB search async"
}

Результат запроса сохранён в поле response.rawData в запрошенном вами виде - XML или HTML - в кодировке Base64.

Результат по конкретному ID вы можете получить в течении 24 часов. После получения результата мы сбрасываем этот ID и результат по нему вы уже получить не сможете.

Формат ошибок:

{
    "code":203, 
    "error":"Повторите запрос через 8 сек."
}