xmlsearch.ru — API поисковой выдачи Яндекса

Обзор

Базовый эндпоинт принимает параметры в query-строке и возвращает XML. Авторизация — по паре user + key. Один вызов = один поисковый запрос; для пакетной обработки есть отдельный batch-эндпоинт.

https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=пластиковые+окна&lr=213&device=desktop

Параметры запроса

Формат ответа

XML в формате Яндекс XML. Результаты идут группами <group> в порядке ранжирования; позиция — атрибут id у <doc>.

<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
  <request>
    <query>пластиковые окна</query>
    <page>0</page>
    <groupings><groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="1"/></groupings>
  </request>
  <response date="20260730T041500">
    <found priority="all">10</found>
    <results>
      <grouping attr="d" mode="deep" groups-on-page="10" docs-in-group="1">
        <page first="1" last="10">0</page>
        <group>
          <doccount>1</doccount>
          <doc id="1">
            <url>https://www.mosokna.ru/</url>
            <domain>www.mosokna.ru</domain>
            <title>Пластиковые окна от производителя в Москве</title>
            <passages><passage>Устанавливаем пластиковые окна и балконные двери…</passage></passages>
          </doc>
        </group>
        <!-- ещё group … -->
      </grouping>
    </results>
  </response>
</yandexsearch>

Поля результата

Новые поля добавляются аддитивно: в JSON — необязательные ключи, в XML — теги только при наличии данных. Существующие поля и их порядок не изменились.

Расширенные блоки

Помимо органики ответ (и XML, и JSON) содержит:

Товары Маркета (details.products) — на mobile и desktop. Домен рекламы — на mobile всегда; на desktop в HTML отсутствует. cache-url — на desktop. Отдельные is_*-флаги и index_size — best-effort и могут быть пустыми.

JSON-формат (format=json)

При format=json ответ — JSON-массив объектов (по объекту на запрос):

[
  {
    "word": "что такое seo",
    "position": 0,
    "index_size": 104000000,
    "results_count": 9, "first_page_organic": 9, "ads_count": 13, "wizards_count": 3, "categories_count": 3,
    "related_queries": ["что такое seo простыми словами", "…"],
    "results": [
      {
        "pos": 1, "serp_pos": 9,
        "domain": "ru.wikipedia.org",
        "url": "https://ru.wikipedia.org/wiki/…",
        "title": "Поисковая оптимизация — Википедия",
        "text": "<b>SEO</b> может генерировать…",
        "cache_url": "https://yandexwebcache.net/…",
        "title_bolds": [], "text_bolds": ["SEO"],
        "is_verified": false, "is_main_page": false
      }
    ],
    "ads": [
      {"block":"top","pos":1,"serp_pos":1,"domain":"direct.yandex.ru","title":"…","text":"…"}
    ],
    "wizards": [
      {"type":"MARKET","side":"LEFT","serp_pos":1,"display_name":"Маркет",
       "details":{"products":[{"title":"Диван-кровать «Жасмин»","price":"12 790","shop":"mnogomeb.ru"}]}},
      {"type":"AI","side":"RIGHT","serp_pos":26,"display_name":"Алиса (LLM-ответ)",
       "details":{"text":"SEO (Search Engine Optimization) — это…","sources":["https://…","https://…"]}}
    ],
    "categories": [
      {"type":"MARKET","side":"LEFT","serp_pos":1,"display_name":"Маркет"},
      {"type":"IMAGES","side":"LEFT","serp_pos":12,"display_name":"Картинки"},
      {"type":"AI","side":"RIGHT","serp_pos":26,"display_name":"Алиса (LLM-ответ)"}
    ],
    "ai_answer": "SEO (Search Engine Optimization) — это…",
    "ai_sources": ["https://…", "https://…"]
  }
]

title и text сохраняют разметку <b>…</b>; *_bolds дублируют выделенные слова списком. Поля ai_answer/ai_sources и details у wizards с type=AI приходят для информационных запросов (быстрый ответ; на mobile и desktop).

Ответ Алисы (LLM)

Для информационных запросов в ответе по умолчанию приходит ответ Алисы — на верхнем уровне и в wizards с type=AI → details. Это быстрый ответ скоростным парсером: приходит всегда, без флагов и доплат — теперь и на device=desktop напрямую (~88%+ запросов), не только на mobile. Может быть неполным. Если Алисы для запроса нет — ai_answer = null.

Текст ответа отдаётся с сохранённой разметкой (заголовки, списки, жирный); технические вставки (inline-сноски, реклама, обвязка, встроенные видео/медиа-карточки) вырезаны, а ссылки-источники идут отдельными полями:

В XML: <wizard type="AI"><ai-text>…</ai-text><ai-meta><footnotes><footnote n="1">URL</footnote>…</footnotes></ai-meta><sources><source>…</source></sources></wizard>.

Ответ Алисы приходит по умолчанию, когда он есть в выдаче — на mobile и desktop, без флагов и доплат. Если Алисы для запроса нет — ai_answer = null. Примеры запросов:

https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=что+такое+seo&device=mobile&format=json
https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=что+такое+seo&device=desktop&format=json

ai=1 — полная Алиса (генерация «на лету»)

Часть запросов (обычно длинные, вопросительные, редкие) Яндекс не отдаёт готовым текстом — в HTML только каркас-заглушка (стрим-тизер), а сам ответ генерируется в реальном времени и дописывается в браузере JS-стримом. Быстрый (бесплатный) режим такой ответ вернуть не может → ai_answer = null.

ai=1 открывает страницу в настоящем headless-браузере, дожидается завершения генерации и возвращает полный текст (тот, что пользователь увидел бы в браузере). Работает и для «нестабильных» desktop-ответов.

• Медленнее: ~7–40 с (браузер + ожидание стрима).
• Дороже: ×10 лимита. Списывается только если полный ответ реально получен; если Алисы для запроса нет вовсе — как обычный запрос (1 лимит).
• Несовместим с top/pages (только при ai=0).
• Когда использовать: обычный ответ вернул ai_answer=null, но нужен именно сгенерированный ответ Алисы.

https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=длинный+вопросительный+запрос&device=desktop&ai=1&format=json

Больше результатов (top / pages / page)

Управление глубиной выдачи. Результаты идут в results со сквозной нумерацией pos = 1…N; у каждого есть поле page (с какой страницы взят). Реклама, спецблоки и related_queries берутся с первой снятой страницы. В ответе — pages_fetched (сколько страниц реально пролистано) и first_page_organic (сколько органики было именно на 1-й странице — при top=N в results_count будет N, а тут — фактическое число органики Яндекса на первой странице). Обычная навигация page работает всегда. Ответ Алисы (ai_answer) при top/pages сохраняется — берётся с первой страницы. alice=1 с top/pages сочетается.

Параметры комбинируются. Стоп — по тому, что срабатывает раньше: цель top или потолок pages.

Тарификация: списывается ровно столько лимитов, сколько страниц пришлось пролистать. Если лимит закончится посреди листания — вернётся набранное, списано за реально пролистанные страницы. Если стартовая страница глубже, чем у Яндекса есть результаты — вернётся ошибка (результатов нет).

https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=пластиковые+окна&device=mobile&top=30
https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=пластиковые+окна&device=mobile&top=30&pages=3
https://xmlsearch.ru/search_yandex/xml?user=USER&key=KEY&query=пластиковые+окна&device=mobile&top=20&page=4

Пакетные запросы (batch)

Один вызов на несколько запросов — обрабатываются параллельно на сервере, ответ приходит одним XML. Параметры lr, device, page, format, related, ai, top, pages, blocked применяются ко всем запросам пачки. При format=json ответ — JSON-массив по запросам. При ai=1 пачка идёт медленнее (браузерный рендер, ограниченная параллельность).

GET — несколько query

https://xmlsearch.ru/search_yandex/batch?user=USER&key=KEY&lr=213&device=desktop&query=пластиковые+окна&query=купить+велосипед&query=ремонт+холодильников

POST — по запросу на строку в теле

curl -X POST "https://xmlsearch.ru/search_yandex/batch?user=USER&key=KEY&lr=213" \
  --data-binary $'пластиковые окна\nкупить велосипед\nремонт холодильников'

Формат ответа batch

<?xml version="1.0" encoding="utf-8"?>
<batch>
  <item query="пластиковые окна">
    <yandexsearch version="1.0"> … </yandexsearch>
  </item>
  <item query="купить велосипед">
    <yandexsearch version="1.0"> … </yandexsearch>
  </item>
</batch>

Если отдельный запрос не удалось снять — у его <item> будет блок <error>, остальные вернутся нормально.

Параллельные запросы

Обработать много запросов одновременно можно двумя способами.

Способ 1 — batch (рекомендуется)

Отправьте все запросы одним POST на /search_yandex/batch — сервер сам распараллеливает их у себя и возвращает ответы одной пачкой. Это самый эффективный путь: одно соединение, минимум накладных расходов, максимальная параллельность на нашей стороне.

curl -X POST "https://xmlsearch.ru/search_yandex/batch?user=USER&key=KEY&lr=213&device=mobile&format=json" \
  --data-binary @queries.txt

queries.txt — по одному запросу на строку. Одна пачка может содержать тысячи запросов; очень длинные списки (десятки тысяч строк) лучше слать частями по 1000–5000, чтобы не держать одно HTTP-соединение слишком долго.

Способ 2 — много одиночных запросов параллельно

Если удобнее слать по одному запросу на соединение — открывайте несколько соединений одновременно, соблюдая правила:

• Переиспользуйте соединения (keep-alive / пул соединений). Не открывайте новый TCP+TLS на каждый запрос — это главный источник тормозов у клиента.
• Конкурентность. Сервер держит до 10 000 одновременных запросов. На практике нескольких десятков–сотен параллельных соединений достаточно, чтобы упереться в потолок скорости (см. ниже); тысячи имеют смысл только на очень больших объёмах.
• Таймаут — не меньше 60 с. Обычный ответ ~1–3 с, но при переборе прокси одиночный запрос может занять до ~30–40 с. Слишком короткий таймаут даёт ложные ошибки и лишние повторы.
• Ретрай на code=500 и таймаутах (1–2 повтора). Это временная неудача съёма; за неуспешный съём лимит не списывается, так что повтор безопасен.
• Не троттлите искусственно. Очередь и параллельность держит сервер — просто не открывайте больше соединений, чем реально успеваете читать.

Пример на Python — 100 параллельных запросов с пулом соединений и ретраем:

import concurrent.futures as cf, requests

USER, KEY = "USER", "KEY"
BASE = "https://xmlsearch.ru/search_yandex/xml"
session = requests.Session()          # пул соединений + keep-alive

def fetch(query):
    for _ in range(3):                # до 3 попыток
        try:
            r = session.get(BASE, params={
                "user": USER, "key": KEY, "query": query,
                "lr": 213, "device": "mobile", "format": "json",
            }, timeout=60)
            data = r.json()[0]         # format=json -> массив из одного объекта
            if "error_code" not in data:
                return data
        except Exception:
            pass
    return None

queries = [s.strip() for s in open("queries.txt", encoding="utf-8") if s.strip()]
with cf.ThreadPoolExecutor(max_workers=100) as pool:   # 100 одновременно
    results = list(pool.map(fetch, queries))

Пропускная способность ограничена не нашим сервером, а скоростью прокси-пула и ответом Яндекса — порядка 1000–1500 запросов в минуту с одного клиента при высокой конкурентности (в тесте 1000 запросов сняты за ~38 с, 1000/1000 успешно). Наращивание числа параллельных соединений сверх этого потолка скорость уже не повышает.

Как получать и сопоставлять ответы

Главное при параллельной работе — надёжно сопоставить каждый ответ с его запросом и обработать ошибки поштучно.

• batch сохраняет порядок. Ответы приходят строго в том порядке, в котором вы прислали запросы. В JSON — массив объектов; в каждом объекте поле word = исходный запрос. В XML — <item query="…"> с тем же порядком и текстом запроса в атрибуте. Сопоставляйте по индексу или по word/query (надёжнее, если не полагаться на порядок).
• Параллельные одиночные — сопоставляйте сами. Каждый ответ при format=json — это массив из одного объекта. Привязывайте ответ к запросу, который вы отправили в данном соединении (например, через словарь future → query). Чтобы обрабатывать ответы по мере готовности, не дожидаясь самого медленного, используйте as_completed.
• Ошибки — на уровне элемента. Не весь ответ падает целиком: у неудачного запроса в JSON есть поле error_code (вместо results), в XML внутри его <item> — блок <error code="…">. Проверяйте это до чтения results; остальные элементы пачки при этом валидны.

Приём параллельных ответов по мере готовности (Python, as_completed):

import concurrent.futures as cf, requests

session = requests.Session()
BASE = "https://xmlsearch.ru/search_yandex/xml"

def fetch(query):
    r = session.get(BASE, params={"user":"USER","key":"KEY","query":query,
                                   "lr":213,"device":"mobile","format":"json"}, timeout=60)
    return r.json()[0]

queries = [s.strip() for s in open("queries.txt", encoding="utf-8") if s.strip()]
answers = {}
with cf.ThreadPoolExecutor(max_workers=100) as pool:
    fut2q = {pool.submit(fetch, q): q for q in queries}   # запоминаем, какой future чей
    for fut in cf.as_completed(fut2q):                     # обрабатываем, как только готов
        q = fut2q[fut]
        try:
            data = fut.result()
        except Exception:
            answers[q] = None; continue                    # сеть/таймаут -> можно ретраить
        if "error_code" in data:
            answers[q] = None                              # съём не удался (лимит не списан)
        else:
            answers[q] = data["results"]                   # успех: список результатов

В batch ничего этого не нужно — сервер отдаёт весь массив разом в исходном порядке; достаточно пройтись по нему и проверить error_code у каждого объекта.

Ошибки

При ошибке возвращается XML с тегом <error>:

<yandexsearch version="1.0"><response><error code="100">wrong user or key</error></response></yandexsearch>

Служебное

GEThttps://xmlsearch.ru/health — проверка доступности (возвращает <ok/>).