Перейти к содержимому
SearchBooster Docs

API рекомендаций

Через API рекомендации встраиваются в свою вёрстку, мобильное приложение или серверный рендер. Основной метод — /widgets/{id}: он применяет все настройки виджета из личного кабинета (алгоритм, фильтры, правила, A/B-тесты, добивку). Остальные методы — простые алгоритмы без настроек виджета.

Рекомендации виджета: /widgets/{id}

Заголовок раздела «Рекомендации виджета: /widgets/{id}»

GET https://api.searchbooster.net/api/{uuid}/widgets/{widgetId}

GET/api/{uuid}/widgets/{widgetId}
Параметр Описание
userId ID посетителя — обязателен для персональных и «недавно просмотренных», нужен для A/B-тестов.
id Товар на странице — для похожих и персональных в карточке.
crossSaleIds Товары в корзине — для «С этим покупают». Можно повторять параметр.
categoryId Категория, ID через запятую.
regionId Регион.
limit До 100, по умолчанию 10.
params Фильтры, как в поиске. Перекрывают фильтры из настроек виджета по тем же полям.
paramKey Имя набора фильтров, сохранённого в виджете.
withNotAvailable Показывать товары не в наличии.
segmentId Сегмент посетителя.
csCategoryLimit Не больше N товаров одной категории в «С этим покупают» — для разнообразия.
imagesSize Размер превью: {"width":300,"height":300}.

Ответ

Заголовок раздела «Ответ»
{
  "offers": [
    { "id": "110244", "name": "Самоедская собака 1984", "price": 2900, "available": true, "url": "…", "pictures": ["…"] }
  ],
  "rid": "0f6e8a1c-2b9d-4c55-9f1e-3a7c1e0d5b42",
  "settings": "{\"titleSettings\":{\"title\":{\"value\":\"Похожие товары\"}}}",
  "experiment": { "id": 3, "widgetId": 402, "variantWidgetId": 411, "bucket": 37 }
}
Поле Описание
offers Товары — те же поля, что в поиске.
rid ID ответа. Передавайте его в аналитику показов (requestId), чтобы клики и покупки связались с этим блоком.
settings Настройки виджета из личного кабинета (JSON-строкой): заголовок, оформление.
experiment Есть, если виджет участвует в A/B-тесте: какой вариант достался посетителю.
payload.tips Для «С этим покупают» — подсказки-категории («Поводки», «Корм»).

Аналитика показов

Заголовок раздела «Аналитика показов»

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

  1. Получили рекомендации → generate.
  2. Блок попал в видимую область → show с ID показанных товаров.
  3. Клик по товару → click.
  4. Покупка из блока — событие purchase в datalayer с widget_id.
fetch(`https://api.searchbooster.net/api/${UUID}/widget-analytics`, {
  method: 'POST',
  headers: { 'Content-Type': 'text/plain;charset=UTF-8' },
  body: JSON.stringify([{
    event: 'show',               // generate | show | click
    widgetId: 402,               // число
    userId,
    itemIds: data.offers.map((o) => o.id),
    requestId: data.rid,
    regionId: 'msk',
    pathname: location.pathname,
  }]),
});

Простые методы

Заголовок раздела «Простые методы»

Без настроек виджета — удобно для быстрых интеграций и прототипов.

Популярные

Заголовок раздела «Популярные»
GET/api/{uuid}/popular

Похожие

Заголовок раздела «Похожие»

GET /api/{uuid}/similar?id=110166&type=0 — type=0 по описанию, type=1 по фото. Параметр filters ограничивает похожесть: [{"type":"priceRange","delta":20}] — цена в пределах ±20%. Подробнее — Похожие по фото.

С этим товаром смотрят и покупают

Заголовок раздела «С этим товаром смотрят и покупают»
GET/api/{uuid}/with-this-product

Строится по сессиям за последние 10 дней из событий POST /recs с session_id. Результат кэшируется на сутки по паре id + requestType.

Популярные бренды

Заголовок раздела «Популярные бренды»

GET /api/{uuid}/popular-brand → ["Bosch", "Makita", …] — до 10 брендов среди популярных товаров со скидкой.