Пошук за допомогою API

Тут описано, як звертатися до Search API, які параметри доступні та які відповіді ви отримаєте в різних сценаріях. Якщо ви прочитали розділ Вступ, то готові до практики.

Ендпоінт

GET /search/v2/

Базовий URL: https://smartsearch.spefix.com/api/v2/search/.

Доступ: публічний, але потребує валідного параметра token.

warning

Якщо не передати q або token, відповідь буде з порожнім набором даних. Це зручно для UX (без «Internal Server Error»), але здатне збити з пантелику під час дебагу.

Параметри запиту

Параметри передаються як query-рядок (наприклад, ?q=phone&token=abc123).

Параметр	Тип	Типове значення	Приклад	Обов'язкове	Опис
q	String	-	"phone"	Так	Пошуковий термін (нечутливий до регістру).
token	String	-	"abc123"	Так	Токен автентифікації (згенерований у Spefix).
language	String	uk	"en"	Ні	Код локалі для назв продуктів/категорій (наприклад, "uk", "ru").
filters	String	-	"1, 2, 3"	Ні	Набір ID значень атрибутів для фільтрації розділених комою.
price_from	Number	-	10.99	Ні	Нижня межа ціни (десяткове число - float).
price_to	Number	-	999.99	Ні	Верхня межа ціни (десяткове число - float).
category_id	String	-	"cat123"	Ні	Фільтр за конкретною категорією (значення source_category_id).
group_by_category	Boolean	true	true	Ні	Групувати результати за категоріями - true чи повертати плаский список - false.
show_unavailable	Boolean	false	true	Ні	Включати відсутні продукти - 'true' або виключати - 'false'.
page	Integer	1	1	Ні	Номер сторінки для пагінації.
product_page_size	Integer	10	10	Ні	Скільки продуктів віддавати на сторінці (для плаского списку або конкретної категорії).
category_page_size	Integer	10	10	Ні	Скільки категорій повертати на сторінці (коли group_by_category=true).
per_category_limit	Integer	3	3	Ні	Максимум продуктів у групі категорії (-1 — без обмежень).
show_filters	Boolean	true	false	Ні	Додавати перелік доступних фільтрів у відповідь.
uuid	String	-	"uuid-123"	Ні	Ваш унікальний ідентифікатор запиту/сесії (для аналітики).
demo	Boolean	false	true	Ні	Якщо true, аналітика не зберігається (режим попереднього перегляду).
use_corrections	Boolean	true	true	Ні	Вмикає виправлення пошукових запитів.
use_suggestions	Boolean	false	false	Ні	Вмикає пропозиції пошукових запитів.

warning

Ми не рекомендуємо використовувати use_corrections і use_suggestions одночасно. Тому якщо обидва значення true, то use_suggestions буде проігноровано. З цієї ж причини, оскільки, use_corrections має значення за замовчуванням true, то щоб увімкнути use_suggestions, необхідно явно передати use_corrections=false.

Структура відповіді

Відповідь — JSON-об'єкт з повними даними для рендерингу результатів:

{
  "total": <number>,                // Загальна кількість знайдених продуктів
  "query": "<string>",              // Оригінальний пошуковий запит
  "corrected_query": "<string>",    // Виправлений запит (якщо застосовано, інакше порожній)
  "suggestions": <array>,           // Впорядкований список пропозицій пошукових запитів (якщо use_suggestions=true)
  "filters_enabled": <boolean>,     // Чи увімкнено фільтри
  "filters": [                      // Доступні фільтри (якщо show_filters=true)
    {
      "id": <number>,               // ID Атрибуту (фільтру)
      "name": "<string>",           // Назва атрибуту
      "values": [
        {
          "id": <number>,           // ID значення атрибута
          "name": "<string>",       // Назва значення (наприклад, "Червоний")
          "total": <number>         // Кількість продуктів, що відповідають цьому значенню
        }
      ]
    }
  ],
  "categories": [                   // Усі відповідні категорії (тільки метадані)
    {
      "id": <number>,               // ID категорії
      "source_id": "<string>",      // Унікальний ID категорії (ID джерела)
      "name": "<string>",           // Назва категорії в локалі
      "url": "<string>",            // URL категорії
      "total": <number>             // Продуктів у цій категорії
    }
  ],
  "products": {
    "groups": [                     // Групи продуктів (за категорією або одна група)
      {
        "source_category_id": "<string>", // ID категорії (порожній, якщо не груповано)
        "category_name": "<string>",     // Назва категорії (порожня, якщо не груповано)
        "category_url": "<string>",      // URL категорії (порожній, якщо не груповано)
        "items": [                       // Продукти в цій групі
          {
            "id": <number>,              // ID продукту
            "source_id": "<string>",     // Унікальний ID продукту (ID джерела)
            "category_id": <number>,     // ID категорії
            "sku": "<string>",           // SKU продукту
            "vendor": "<string>",        // Виробник (Бренд)
            "name": "<string>",          // Назва продукту (згідно до language)
            "url": "<string>",           // URL продукту
            "price": <number>,           // Оригінальна ціна
            "discounted_price": <number>,// Ціна зі знижкою (якщо застосовується)
            "currency": "<string>",      // Код валюти (наприклад, "USD")
            "picture_url": "<string>",   // URL зображення
            "availability": <boolean>,   // Чи доступний продукт?
            "labels": [                  // Опціональні мітки (наприклад, "Новий", "Розпродаж")
              {
                "name": "<string>",
                "color": "<string>"      // Hex-колір (наприклад, "#FF0000"), або порожній рядок
              }
            ]
          }
        ]
      }
    ]
  },
  "pagination": {                   // Метадані пагінації
    "type": "<string>",             // "products" або "categories"
    "current_page": <number>,       // Поточна сторінка
    "page_size": <number>,          // Кількість продуктів або категорій на сторінці
    "total_items": <number>,        // Загальна кількість продуктів або категорій
    "total_pages": <number>,        // Загальна кількість сторінок
    "has_next": <boolean>,          // Чи є наступна сторінка?
    "has_previous": <boolean>       // Чи є попередня сторінка?
  }
}

tip

Поле corrected_query корисно для відображення "Ви мали на увазі: phones?" у UI.

---

Формати відповіді залежно від групування

1. Групування за категоріями

group_by_category=true (без category_id)

• products.groups: містить category_page_size груп, одна група на категорію, кожна містить до per_category_limit продуктів
• categories: містить метадані категорій (всіх, а не лише тих що є в products.groups)
• Пагінація: За категоріями category_page_size; pagination.type: "categories".
• Використання: відображення на основі категорій (наприклад, розділи «Телефони», «Аксесуари»)

Приклад

2 категорії на сторінці, по 3 товари в кожній — ідеально для десктопного пошуку.

---

2. Запит у межах однієї категорії

category_id надано, group_by_category=true || group_by_category=false

• products.groups: одна група для вказаної категорії, містить до product_page_size продуктів
• categories: містить метадані всіх категорій (не залежно від category_id)
• Пагінація: Пагінація: За товарами product_page_size; pagination.type: "products".
• Використання: коли користувач обирає категорію (наприклад, клікнув «Телефони»)

Приклад

10 товарів з категорії "cat123" — для сторінки товарів.

---

3. Плаский список (без групування)

group_by_category=false, без category_id

• products.groups: одна група з усіма продуктами, без інформації про категорію, містить до product_page_size продуктів
• Пагінація: За товарами; pagination.type: "products".
• categories: містить метадані всіх категорій.
• Використання: плаский список (усі продукти в одному списку, незалежно від категорій)

tip

Приклад: 5 товарів на сторінці, змішані з усіх категорій — для швидкого перегляду.