Товары и фильтры в Search API

Эта страница описывает структуру товаров и фильтров, которые возвращает /api/v1/search и использует виджет Relavio Search. Эти данные формируются из импортированного каталога и поискового индекса.

Объект товара

Товар в ответе поиска выглядит так:

{
  "position": 1,
  "id": "iphone-15-128",
  "title": "iPhone 15 128GB Black",
  "brand": "Apple",
  "model": "A3090",
  "categories": ["Смартфоны", "Apple"],
  "price": 99990,
  "old_price": 109990,
  "currency": "RUB",
  "available": true,
  "quantity": 12,
  "image": "https://example.com/images/iphone-15.jpg",
  "url": "https://example.com/products/iphone-15-128",
  "rating": 4.8,
  "reviews_count": 125,
  "score": 12.57
}

Поля товара

Поле	Тип	Описание
position	integer	Позиция товара в выдаче с учетом страницы.
id	string/null	Идентификатор товара из индекса.
title	string/null	Название товара.
brand	string/null	Бренд.
model	string/null	Модель, если она была импортирована.
categories	array	Список названий категорий.
price	number/null	Текущая цена.
old_price	number/null	Старая цена.
currency	string/null	Валюта товара, например RUB.
available	boolean	Признак наличия.
quantity	integer	Количество, если оно есть в индексе.
image	string/null	Основное изображение.
url	string/null	Ссылка на страницу товара.
rating	number/null	Рейтинг товара.
reviews_count	integer	Количество отзывов.
score	number/null	Поисковый score.

Как товар отображается в виджете

Виджет использует несколько альтернативных названий полей, чтобы поддерживать разные форматы ответа, но стандартный Search API возвращает поля из таблицы выше.

В карточке товара виджет показывает:

• изображение из image;
• название из title;
• описание из brand, model и categories, если нет отдельного описания;
• цену из price;
• старую цену из old_price;
• ссылку из url.

Если image отсутствует, виджет показывает встроенный placeholder. Если url отсутствует или включен disableProductLinks, карточка не будет ссылкой.

Позиция товара

position считается на стороне API с учетом страницы и per_page.

Например при page: 2 и per_page: 20 первый товар страницы получит position: 21.

Эта позиция отправляется в аналитику кликов, чтобы понимать, какие места выдачи получают переходы.

Фильтры в ответе

Фильтры возвращаются в поле filters, если в запросе /api/v1/search передано withFilters: true.

{
  "code": "brand",
  "name": "Бренд",
  "type": "terms",
  "values": [
    {
      "value": "Apple",
      "count": 12
    },
    {
      "value": "Samsung",
      "count": 8
    }
  ]
}

Типы фильтров

terms

Список значений. Используется для брендов, категорий и строковых характеристик.

{
  "code": "brand",
  "name": "Бренд",
  "type": "terms",
  "values": [
    {
      "value": "Apple",
      "count": 12
    }
  ]
}

В запросе выбранные значения передаются массивом:

{
  "filters": {
    "brand": ["Apple"]
  }
}

range

Диапазон числовых значений. Используется для цены и числовых атрибутов.

{
  "code": "price",
  "name": "Цена",
  "type": "range",
  "min": 1000,
  "max": 200000
}

Для атрибутов может вернуться unit:

{
  "code": "diagonal",
  "name": "Диагональ",
  "type": "range",
  "min": 5.4,
  "max": 6.9,
  "unit": "дюйм"
}

В запросе диапазон передается объектом:

{
  "filters": {
    "price": {
      "from": 50000,
      "to": 120000
    }
  }
}

boolean

Булевый фильтр. Используется для значений, которые в индексе представлены как true или false.

{
  "code": "available",
  "name": "Наличие",
  "type": "terms",
  "values": [
    {
      "value": true,
      "count": 30
    }
  ]
}

Системный фильтр наличия возвращается как terms, а пользовательские булевые атрибуты могут возвращаться как boolean.

Системные фильтры

Search API может вернуть системные фильтры:

• price - диапазон цен;
• brand - бренды;
• category - категории;
• available - наличие.

Дополнительно возвращаются фильтры по атрибутам товаров, которые были импортированы через <param> в YML или другим способом.

Рекомендации для качества карточек

Чтобы карточки в виджете выглядели полно, передавайте при импорте:

• стабильный ID товара;
• понятное название;
• бренд и категории;
• актуальную цену и старую цену;
• изображение хорошего качества;
• абсолютную или корректно собираемую ссылку на товар.