ЯндексXML. Руководство разработчика
ЯндексXML - Формат запроса
С последними нововведениями от Яндекса, появилось несколько режимов отправки запросов и получения результатов: Синхронный режим (отключен), Гибридный режим (в реальном времени) и Асинхронный режим (с задержкой).
Запрос результатов поиска в Синхронном режиме
Синхронный режим — режим работы API, при котором запрос выполняется и возвращает результат в рамках одного HTTP-запроса. В синхронном режиме клиент отправляет запрос и ожидает его обработки. По завершении выполнения запроса сервер сразу возвращает ответ с найденными результатами. С 1 марта 2025 года на этот режим Яндекс повысил цену до 480 руб за 1000 запросов, в связи с этим он был отключен и более не используется.
Запрос результатов поиска в Асинхронном режиме
Асинхронный режим — режим работы API, при котором запрос на поиск ставится в очередь, и результат можно получить позже с помощью отдельного запроса. Запросы выполняются в два этапа: сначала клиент отправляет запрос, получая идентификатор задачи (req_id), а затем отдельно запрашивает результат выполнения. Для отправки запроса в асинхронном режиме достаточно добавить дополнительный параметр к запросу: &delayed=1
В ответ вы получите идентификатор задачи в следующем формате:
<?xml version="1.0" encoding="UTF-8"?>
<yandexsearch version="2.0">
<response date="20250204T185502">
<req_id>spr3s0ngc4citnd30muk</req_id>
</response>
</yandexsearch>
Далее дождитесь, пока система выполнит запрос и сформирует ответ. На это может потребоваться от нескольких секунд до нескольких часов. Через 5-10 секунд пробуйте получить результат используя индентификатор задачи, который получили ранее, отправляя запрос с параметром &req_id=spr3s0ngc4citnd30muk
Если результат готов, сервер возвращает стандартный XML-ответ с данными поисковой выдачи. В противном случае отправляется ошибка с кодом 202, указывающая, что запрос еще не обработан, и рекомендуется повторить попытку позже. Повторную проверку готовности разрешается выполнять не чаще чем один раз в 5-10 секунд. Полный список возможных ошибок представлен на странице «Коды ошибок».
Списание средств происходит в момент получения req_id, независимо от того, был ли позже вами отправлен запрос на получение данных или нет.
Запрос результатов поиска в Гибридном режиме
Гибридный режим — режим работы API, который сочетает в себе элементы синхронного и асинхронного режимов. Он основан на асинхронном механизме, но имитирует поведение синхронного. Этот режим предназначен для поддержки программ, не успевших полностью перейти на асинхронную модель. Приложения, такие как Key Collector, Top-Site и другие, также работают с ним. Результаты выдачи возвращаются сразу при наличии данных, однако время обработки запроса может быть несколько увеличено. В некоторых случаях вместо результатов могут приходить коды ошибок 202 или 210, означающие что запрос еще не обработан. Гибридный режим включен по умолчанию для всех пользователей.
Запрос в данном режиме отправлятся точно также как и в синхронном:
В ответ вы получите либо готовую выдачу, либо ошибку в следующем формате:
<?xml version="1.0" encoding="UTF-8"?>
<yandexsearch version="1.0">
<response date="20250301T105416">
<error code="210">Запрос поставлен в очередь и будет обработан. Для получения данных отправьте его повторно через несколько секунд.</error>
</response>
</yandexsearch>
При получении таких ошибок повторите запросы, которые не удалось обработать с первого раза и которые были поставлены в очередь, через 5–10 секунд. Если данные уже готовы, результат будет возвращен сразу. В противном случае вы получите ошибку 202 (запрос еще не обработан).
Запросы, поставленные в очередь с ошибкой 210, кешируются системой и обрабатываются по мере готовности. Повторные запросы к уже закешированным результатам в течение 3 часов — бесплатны.
Если данные по-прежнему недоступны, продолжайте повторные запросы с интервалом 10–20 секунд до получения результата. Списание средств происходит только при первой отправке запроса в API, независимо от того, был ответ получен сразу или запрос поставлен в очередь.
При необходимости кеш запросов можно сбросить в личном кабинете, нажав кнопку "Сбросить кеш", либо с помощью API, отправив запрос с параметром cache=reset. В настоящее время наблюдается высокая скорость работы данного режима, все запросы проходят немедленно без кеширования, полностью имитируя работу синхронного режима.
Запрос результатов мобильной выдачи
Для получения мобильных результатов выдачи необходимо к запросу добавить параметр &device=mobile
