На этой странице

Веб-поиск

Живой поиск по русскоязычному и глобальному вебу. Возвращает очищенные результаты без рекламы и навигации, инфобоксы, готовые ответы и подсказки - плюс метаданные о размере и времени.

POSThttps://srezai.ru/api/v1/search

Пример запроса

bash
curl -X POST https://srezai.ru/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer srz_live_ВАШ_КЛЮЧ" \
  -d '{
    "query": "квантовые вычисления обзор 2026",
    "category": "science",
    "timeRange": "year",
    "language": "ru",
    "num": 10,
    "excerpts": true
  }'

Параметры тела

Тело запроса - JSON. Обязателен только query; неизвестные или недопустимые значения остальных полей мягко заменяются значением по умолчанию.

querystringобязательный

Поисковый запрос. Пробелы схлопываются, обрезается до 300 символов. Пустой запрос вернёт ошибку 400.

categorystringнеобязательный

Набор поисковых движков. Одно из: general (по умолчанию), news, it, science. См. ниже.

timeRangestringнеобязательный

Свежесть по дате публикации: ""/all (без ограничения, по умолчанию), day, week, month, year - окно в 1, 7, 30 и 365 дней от сегодняшнего дня. Фильтр применяем мы, а не движок: страницы без даты публикации в окно не проходят. Перед отбрасыванием дату добираем - сперва из адреса страницы (/2026/09/24/…), потом у той же ссылки в выдаче другого движка, а если выдача от этого укорачивается, то из метатегов самой страницы (до 14 адресов, 3 секунды на адрес). Что не добрали - отброшено, и это видно в поле freshness.

publishedAfterstringнеобязательный

Нижняя граница даты публикации, YYYY-MM-DD включительно. Сильнее timeRange, если заданы оба.

publishedBeforestringнеобязательный

Верхняя граница даты публикации, YYYY-MM-DD включительно. Вместе с publishedAfter задаёт точное окно, например «события ноября 2026»: {"publishedAfter": "2026-11-01", "publishedBefore": "2026-11-30"}.

languagestringнеобязательный

Язык выдачи: auto (по умолчанию), ru, en.

numnumberнеобязательный

Желаемое число результатов, от 1 до 30. Фактическое количество зависит от ответов движков.

excerptsbooleanнеобязательный

Если true, для топовых результатов подтягивается реальный фрагмент текста страницы под запрос (поле excerpt, до 1200 символов) - готовый контекст для ответа без перехода на сайт. По умолчанию false; добавляет 3-10 секунд (страницы читаются параллельно). Если страница недоступна, поле остаётся пустым (мягкая деградация - остаётся content).

chunksPerSourcenumberнеобязательный

Сколько кусков текста вернуть на каждый из топ-4 результатов, от 0 до 5 (по умолчанию 0). Куски вырезаны из страницы по релевантности запросу и идут по порядку; под них страница читается глубже - до 600 × N символов, тогда как excerpt даёт только 1200. Один вызов отдаёт контекст, за которым иначе пришлось бы идти в read_url; цена вызова не меняется. Замер: пять результатов с обычными сниппетами - 835 символов, с тремя кусками - около 3000 на тех же страницах.

includeRawContentbooleanнеобязательный

Если true, для топ-4 результатов возвращается полный текст страницы (поле rawContent, до 20 000 символов на результат) - замена отдельному чтению. По умолчанию false. Осторожно с num: это десятки тысяч токенов, берите 1-3 результата. Страницы, которые не удалось прочитать, возвращаются с пустым rawContent - остальные результаты от этого не страдают.

includeDomainsstring[]необязательный

Искать только на этих сайтах, включая поддомены: до 10 доменов, ["habr.com", "vc.ru"]. См. раздел Фильтр по доменам.

excludeDomainsstring[]необязательный

Исключить эти сайты и их поддомены: до 10 доменов, ["pinterest.com"]. Можно комбинировать с includeDomains.

Категории

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

  • general - универсальный поиск (Yandex, DuckDuckGo, Bing, Startpage, Mojeek, Википедия).
  • news - новости (Yandex, Google News, Bing, DuckDuckGo).
  • it - разработка (GitHub, Stack Overflow, MDN, DuckDuckGo).
  • science - научные публикации (PubMed, DuckDuckGo, Bing).

Фильтр по доменам

includeDomains ограничивает выдачу перечисленными сайтами, excludeDomains - убирает их. Оба списка принимают до 10 доменов и работают вместе.

json
{
  "query": "next.js app router роутинг",
  "category": "it",
  "includeDomains": ["habr.com", "vc.ru"],
  "excludeDomains": ["pinterest.com"]
}
  • Поддомены попадают под правило автоматически: habr.com включает и habr.com, и blog.habr.com.
  • Формат - домен: example.com. Полный URL (https://www.example.com/blog) тоже принимается - из него берётся хост. www. отбрасывается, регистр не важен, кириллические домены (хабр.рф) поддерживаются.
  • Домены применяются дважды: как оператор в запросе к движкам и как фильтр по хосту результата. Поэтому в выдаче гарантированно нет посторонних сайтов, даже если движок оператор проигнорировал.
  • Под фильтром выдача может быть пустой - это нормальный ответ 200 с results: [], а не ошибка. Проверьте домены или снимите ограничение.
  • Если список непустой, но ни одна строка не распознана как домен, вернётся 400 - фильтр не применяется молча.

Ответ

json
{
  "query": "квантовые вычисления обзор 2026",
  "results": [
    {
      "title": "Обзор квантовых вычислений",
      "url": "https://example.ru/quantum",
      "content": "Краткое описание страницы без разметки…",
      "engine": "pubmed",
      "category": "science",
      "source": "example.ru",
      "score": 1.42,
      "relevance": 0.87,
      "publishedDate": "2026-03-11T00:00:00",
      "semantic": 0.94,
      "excerpt": "Реальный фрагмент текста страницы под запрос (при excerpts: true)…"
    }
  ],
  "infoboxes": [
    {
      "title": "Квантовый компьютер",
      "content": "Устройство для вычислений…",
      "urls": [{ "title": "Википедия", "url": "https://ru.wikipedia.org/…" }]
    }
  ],
  "answers": [],
  "suggestions": ["квантовая запутанность", "кубит"],
  "unresponsiveEngines": [],
  "producedBy": 1,
  "attempts": 1,
  "relaxedQuery": null,
  "degraded": false,
  "meta": {
    "total": 12,
    "tookMs": 640,
    "rawBytes": 84210,
    "cleanBytes": 5120
  }
}

Поля ответа

resultsarrayнеобязательный

Результаты поиска (количество задаётся num), пересортированы по релевантности запросу. Каждый содержит title, url (кириллица декодирована для читаемости), content, engine, category, source (домен без www), score (агрегация движка), relevance (лексическая близость запросу, 0…1), semantic (семантическая близость от BGE-reranker, 0…1, или null), publishedDate (или null), dateSource (откуда взялась дата: engine, other-engine, url, page) и excerpt (реальный текст страницы при excerpts: true, иначе пустая строка).

semanticobject | nullнеобязательный

Итог семантического ранжирования: applied (применилось ли), docs (сколько результатов оценили), tookMs и reason (ok, off, few-results, unavailable). Порядок верхних 12 результатов считается как relevance × (0,5 + 0,5 × semantic): семантика может понизить страницу, у которой совпали слова, а смысла нет, но не может вытащить наверх страницу со слабой лексикой. Сервис задаётся переменной RERANK_URL (по умолчанию http://bge-reranker:8002); не ответил - порядок остаётся лексическим, а в поле видно unavailable.

chunksstring[]необязательный

Куски текста страницы под запрос (chunksPerSource> 0, у топ-4 результатов). Первый кусок совпадает с excerpt, дальше - продолжение по релевантности. Пустой массив, если не просили.

rawContentstringнеобязательный

Полный текст страницы (includeRawContent: true, у топ-4 результатов), до 20 000 символов. Пустая строка, если не просили или страница не прочиталась.

infoboxesarrayнеобязательный

До 3 инфобоксов (краткая справка с ссылками), если движок их вернул.

answersstring[]необязательный

Прямые ответы от источников (например, калькуляторы, определения).

suggestionsstring[]необязательный

Похожие запросы для уточнения поиска.

freshnessobject | nullнеобязательный

Что сделал фильтр свежести: null - фильтра не было; иначе window (какой фильтр применили), kept (сколько результатов осталось), droppedUndated (сколько отброшено из-за отсутствия даты публикации) и droppedOutOfRange (сколько не попало в окно). Там же datesFromUrl, datesFromOtherEngine и datesFromPage - сколько дат добрали и откуда. Пустая выдача под фильтром - чаще всего сам фильтр, а не отсутствие информации; по этим числам видно, что убирать.

unresponsiveEnginesarrayнеобязательный

Движки, не ответившие вовремя. Выдача мягко деградирует - остальные движки всё равно возвращают результаты. Если не ответил ни один, приходит 503 с кодом search_unavailable, а не пустая выдача.

metaobjectнеобязательный

total - число результатов, tookMs - время запроса, rawBytes/cleanBytes - размер сырого и очищенного ответа (наглядно показывает экономию токенов).

Остаток лимита приходит в заголовках X-RateLimit-*, а не в теле ответа - см. Лимиты и квоты.