Подсказки

Подсказки — то, что пользователь видит в выпадающем окне, пока печатает: популярные запросы, категории, бренды, товары и его собственная история поиска. Метод быстрее /search и рассчитан на вызов на каждое нажатие клавиши.

GET https://api.searchbooster.net/api/v2/{uuid}/completions

🔎 тер

🕘 терьер для квартирыhistory

🔥 терьер щенокpopular

↗ терьер джек расселsuggestions

Категории

📁 Керн-терьер 197categories

📁 Той-терьер 172categories

🏷 Nordic Kennelbrands

🎁 Скидки до −30% на кормаspecial_offers

Товары offers[]

🐕Керн-терьер 4 · 39 800 ₽

🐕Той-терьер 81 · 166 700 ₽

🐕Норвич-терьер 12 · 24 500 ₽

Каждая строка — элемент searchBox с типом в поле label; товары приходят отдельным массивом offers.

GET/api/v2/{uuid}/completions

uuid проектДемо-проект SearchBooster. Подставьте UUID своего проекта из личного кабинета.queryuserIdcompletionSettingsКакие блоки, в каком порядке и сколько. Необязательно.regionId

Параметры

Параметр	Описание
`query`	Что ввёл пользователь. Пустой запрос — стартовый экран.
`userId`	ID посетителя — для блока «История».
`completionSettings`	JSON: состав и порядок блоков (ниже).
`limit`	Сколько товаров вернуть (перекрывает `limits.offers`).
`regionId`, `categoryId`, `params`	Как в `/search`: регион, ограничение категорией, фильтры.

completionSettings

{
  "orders": ["history", "popular", "categories", "brands", "suggestions", "special_offers", "offers"],
  "totalCompletionCount": 12,
  "limits": { "history": 6, "popular": 6, "categories": 6, "brands": 6, "suggestions": 6, "special_offers": 3, "offers": 6 }
}

Это значения по умолчанию. orders задаёт порядок блоков и заменяет значение целиком, limits дополняет значения по умолчанию, totalCompletionCount — общий лимит текстовых подсказок.

Блок	Что это
`history`	Прошлые запросы этого `userId` (по префиксу).
`popular`	Популярные запросы магазина.
`suggestions`	Продолжения запроса.
`categories`	Категории — клик ведёт в категорию.
`brands`	Бренды — клик ведёт на поиск с фильтром по бренду.
`special_offers`	Ваши акции и ссылки из CSV своих подсказок.
`offers`	Товары — в отдельном массиве `offers`.

Ответ

{
  "searchBox": [
    {
      "label": "categories",
      "text": { "value": "Керн-терьер", "html": "Керн-<strong>тер</strong>ьер" },
      "id": "7880",
      "count": 197,
      "url": "https://shop.ru/c/kern-terrier",
      "search": { "query": "", "categoryId": "7880" }
    },
    {
      "label": "brands",
      "text": { "value": "Nordic Kennel", "html": "Nordic Kennel" },
      "search": { "query": "", "params": [{ "field": "vendor", "condition": "in", "options": ["Nordic Kennel"] }] }
    }
  ],
  "offers": [{ "id": "99839", "name": "Керн-терьер 4", "price": 39800, "url": "…", "pictures": ["…"] }],
  "tips": [],
  "redirect": "",
  "meta": {}
}

searchBox — текстовые подсказки. Тип — в поле label; text.html содержит подсветку <strong> совпавшей части.
search — что сделать по клику: выполнить /search с search.query, search.categoryId и search.params. Если есть url (категория, акция) — можно перейти по ссылке.
offers — карточки товаров, как в /search.
redirect — если для запроса настроен редирект, переходите сразу по Enter.

Как реализовать окно подсказок

let controller;
input.addEventListener('input', debounce(async () => {
  controller?.abort();                       // отменяем устаревший запрос
  controller = new AbortController();
  const url = new URL(`https://api.searchbooster.net/api/v2/${UUID}/completions`);
  url.searchParams.set('query', input.value);
  url.searchParams.set('userId', getCookie('searchbooster_v2_user_id'));
  const data = await (await fetch(url, { signal: controller.signal })).json();
  renderDropdown(data.searchBox, data.offers);
}, 150));

Debounce 120–200 мс и отмена предыдущего запроса.
Открывайте окно по фокусу даже с пустым полем — там история и популярное.
По Enter вызывайте /search; если в ответе подсказок был redirect — переходите по нему.
Отправляйте клики по товарам из подсказок как событие с type=productClickCompletions.