Suggest API

Suggest API возвращает данные для автодополнения в виджете Relavio Search. Endpoint используется режимом suggests и каталоговыми режимами перед полноценным поиском: показывает историю, текстовые подсказки, категории, бренды и товары.

Endpoint

POST /api/v1/search/suggests

Запрос требует API-ключ магазина.

Accept: application/json
Content-Type: application/json
api-key: YOUR_API_KEY

Тело запроса

{
  "query": "iph",
  "session_id": "session-123"
}

Параметры

Поле	Тип	Обязательность	Описание
query	string	Нет	Часть поискового запроса.
session_id	string	Нет	Идентификатор пользовательской сессии. Если не передать, API создаст новый.

Виджет передает query, session_id и текущий search_id, если он уже был получен. Фильтры в запрос подсказок не отправляются.

Пример ответа

{
  "data": {
    "autocomplete_id": "autocomplete-123",
    "session_id": "session-123",
    "history": [
      "iphone",
      "airpods"
    ],
    "suggestions": [
      "iphone 15",
      "iphone 15 pro"
    ],
    "categories": [
      {
        "name": "Смартфоны"
      }
    ],
    "brands": [
      {
        "name": "Apple"
      }
    ],
    "products": [
      {
        "position": 1,
        "id": "iphone-15-128",
        "title": "iPhone 15 128GB Black",
        "price": 99990,
        "image": "https://example.com/images/iphone-15.jpg",
        "url": "https://example.com/products/iphone-15-128"
      }
    ]
  },
  "error": {
    "code": 0,
    "message": ""
  }
}

Поля ответа

Поле	Описание
autocomplete_id	Идентификатор операции автодополнения. Виджет использует его как search_id для последующих событий.
session_id	Идентификатор пользовательской сессии.
history	История поисковых запросов пользователя в рамках магазина и сессии.
suggestions	Текстовые подсказки из поискового индекса.
categories	Категории, подходящие под запрос. Каждый элемент содержит name.
brands	Бренды, подходящие под запрос. Каждый элемент содержит name.
products	Товары, которые можно показать прямо в выпадающем списке.

Поведение виджета

В режиме suggests виджет отображает секции:

• История из history;
• Подсказки из suggestions;
• Категории из categories;
• Товары из products.

Клик по текстовой подсказке или категории подставляет ее в поле поиска и запускает полноценный поиск через /api/v1/search.

Клик по товару ведет на url, если ссылка есть и не включен параметр disableProductLinks. Одновременно виджет отправляет событие клика в /api/v1/search/events.

Сессия и cookie

Если session_id не передан, API создает новую сессию. Ответ может установить cookie session_id и search_id, которые будут использоваться следующими запросами виджета.

Ошибки

401 Unauthorized

API-ключ отсутствует или неверный.

422 Validation Error

Некорректный тип поля. Например session_id передан не строкой.

Когда использовать напрямую

Используйте Suggest API напрямую, если вы создаете собственный UI поиска вместо стандартного виджета. Для стандартной установки достаточно подключить виджет и выбрать data-behavior="suggests".