Фильтры и фасеты

Фильтры передаются параметром params — JSON-массивом условий. Условия объединяются через И; внутри одного условия in значения объединяются через ИЛИ. Чтобы построить панель фильтров, используйте фасеты из ответа /search — в них уже есть доступные значения и количество товаров.

Отметьте фильтры в демо — в логе справа видно, какой params уходит в API:

🐾 demo-shop

Запросы к API в реальном времени

Условия

condition	Поля	Пример
in	options — массив значений	{"field":"vendor","condition":"in","options":["Bosch","Makita"]}
not_in	options	{"field":"Цвет","condition":"not_in","options":["белый"]}
equal	value	{"field":"_is_available","condition":"equal","value":true}
range	min, max — строки	{"field":"price","condition":"range","min":"1000","max":"5000"}
multirange	minField, maxField, ranges	{"condition":"multirange","minField":"Ширина","maxField":"Ширина","ranges":[{"min":"10","max":"20"},{"min":"40","max":""}]}

min и max — строки

{"min": 1000} вернёт 400 Bad Request. Передавайте {"min": "1000"}. Одну из границ можно не указывать.

Поля

field	Что фильтрует
price	Цена (с учётом regionId).
vendor	Бренд.
category	ID категорий; подкатегории включаются.
available	Наличие в регионе.
pickup, delivery, preorder	Самовывоз, доставка, предзаказ.
id	ID товаров — например, чтобы показать подборку.
название параметра	Любой <param name="…"> из фида, без учёта регистра: "Цвет", "Мощность".
свой тег	Любой нестандартный тег фида: "rating", "margin".

Пример — белые собаки до 5 000 ₽ в наличии:

GET/api/{uuid}/search

uuid проектДемо-проект SearchBooster. Подставьте UUID своего проекта из личного кабинета.querylimitparams [{"field":"price","condition":"range","min":"0","max":"5000"},{"field":"качество","condition":"in","options":["Премиум","Высокое"]}]

cURLJavaScriptPHPPythonКопировать

Отправить запрос⌘↵

Фасеты в ответе

В поле params ответа /search приходят фасеты — описания фильтров с доступными значениями для текущего запроса:

"params": [
  {
    "id": "category", "name": "category", "type": "multiple",
    "options": [{ "id": "8145", "name": "Самоедская собака", "hits": 218 }]
  },
  { "id": "price", "name": "price", "type": "range", "minValue": 55, "maxValue": 198700 },
  {
    "id": "kachestvo", "name": "качество", "originalName": "Качество", "type": "multiple",
    "options": [{ "id": "Премиум", "name": "Премиум", "hits": 888 }]
  },
  { "id": "_is_available", "name": "_is_available", "type": "checkbox", "value": "true", "options": [{ "id": "true", "hits": 50 }] }
]

type	Как показывать	Как фильтровать
multiple	Список чекбоксов	in с выбранными options[].name (для категорий — options[].id)
color	Цветные кружки	in
toggle	Переключатель	in
checkbox	Один флажок («В наличии»)	equal
range	Слайдер «от — до» по minValue / maxValue	range

Какое имя передавать в field

Для параметров фида используйте название (originalName или name), а не id фасета: id — служебный хеш. Для категорий — "category" и ID категорий в options.

Какие параметры становятся фасетами, их порядок, тип и названия настраиваются в личном кабинете (Фильтры). Фасеты считаются по всей выдаче, а не по текущей странице.

Сценарий: панель фильтров

async function searchWithFilters(query, selected, price) {
  const params = Object.entries(selected)
    .filter(([, values]) => values.length)
    .map(([field, options]) => ({ field, condition: 'in', options }));
  if (price) params.push({ field: 'price', condition: 'range', min: String(price.min), max: String(price.max) });

  const url = new URL(`https://api.searchbooster.net/api/${UUID}/search`);
  url.searchParams.set('query', query);
  url.searchParams.set('limit', '24');
  if (params.length) url.searchParams.set('params', JSON.stringify(params));
  return (await fetch(url)).json(); // data.params → перерисуйте панель, data.offers → сетку
}

После каждого изменения фильтров перерисовывайте панель из нового params: количество товаров в значениях пересчитывается под выбранные фильтры.

Фильтры работают одинаково в /search, /completions, рекомендациях (/widgets/{id}, /popular, /similar) и /search/structure-by-category.