Skip to content

Интеграция с использованием API

Поиск может быть интегрирован на сайт или в приложении при помощи API - документация swagger.

вебинар по API SearchBooster .

Поиск

Основной метод поиска - /search,

Пример запроса:

https://api.searchbooster.net/api/ca8fc618-9ee9-48f1-b9b6-92e810424297/search?query=соб&limit=1

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

{
    "topOffersIds": [],
    "offers": [
        {
            "available": true,
            "id": "110166",
            "score": 28.942768,
            "name": "Самоедская собака 1",
            "url": "https://demo.searchbooster.io/product/%d1%81%d0%b0%d0%bc%d0%be%d0%b5%d0%b4%d1%81%d0%ba%d0%b0%d1%8f-%d1%81%d0%be%d0%b1%d0%b0%d0%ba%d0%b0-1/",
            "price": 960,
            "oldPrice": 1200,
            "currency": "RUR",
            "pictures": [
                "https://slc.searchbooster.io/go_epWGY8CPz1vdaEVpxppaDxDuFE784qYqWUS8sVhw/rs:fit:200:300:0:sm/aHR0cHM6Ly9kZW1vLnNlYXJjaGJvb3N0ZXIuaW8vd3AtY29udGVudC91cGxvYWRzL24wMjExMTg4OV8xOTg0LmpwZw.jpeg"
            ],
            "category": {
                "id": "8145",
                "name": "Самоедская собака"
            },
            "categories": [
                {
                    "id": "8145",
                    "name": "Самоедская собака"
                }
            ]
        }
    ],
    "extraOffers": null,
    "ads": [],
    "hits": 905,
    "categories": [
        {
            "hits": 218,
            "id": "8145",
            "name": "Самоедская собака",
            "score": 28.942768096923828
        },
        {
            "hits": 213,
            "id": "8144",
            "name": "Пиренейская горная собака",
            "score": 24.499252319335938
        },
        {
            "hits": 155,
            "id": "8163",
            "name": "Мексиканская голая собака",
            "score": 24.037940979003906
        },
        {
            "hits": 169,
            "id": "8176",
            "name": "Африканская охотничья собака",
            "score": 22.752670288085938
        },
        {
            "hits": 150,
            "id": "8116",
            "name": "Американская эскимосская собака",
            "score": 21.96955108642578
        }
    ],
    "params": [
        {
            "id": "category",
            "name": "category",
            "type": "multiple",
            "options": [
                {
                    "id": "8145",
                    "hits": 218,
                    "name": "Самоедская собака",
                    "score": 28.942768096923828
                },
                {
                    "id": "8144",
                    "hits": 213,
                    "name": "Пиренейская горная собака",
                    "score": 24.499252319335938
                },
                {
                    "id": "8163",
                    "hits": 155,
                    "name": "Мексиканская голая собака",
                    "score": 24.037940979003906
                },
                {
                    "id": "8176",
                    "hits": 169,
                    "name": "Африканская охотничья собака",
                    "score": 22.752670288085938
                },
                {
                    "id": "8116",
                    "hits": 150,
                    "name": "Американская эскимосская собака",
                    "score": 21.96955108642578
                }
            ]
        },
        {
            "id": "price",
            "name": "price",
            "type": "range",
            "maxValue": 198700,
            "minValue": 55
        }
    ],
    "query": "соб",
    "suggestions": null,
    "meta": {
        "searchType": [
            "narrow-autocomplete"
        ],
        "searchTypePassed": [
            "narrow-autocomplete"
        ]
    }
}

Параметр searchType отвечает за уровень, на котором нашлись товары. Если уровень отличается от narrow-* - поиск сработал по неточному соответствию.

Помимо описанных в документации параметров метод принимает также GET-параметр:

  • userParams (JSON):

  • width - ширина экрана пользователя;

  • height - высота экрана пользователя;

  • userAgent - User agent — идентификационная строка клиентского приложения.

Пагинация

Для пагинации используются параметры skip и limit.

  • skip: Этот параметр указывает, сколько записей нужно пропустить перед тем, как начать возвращать результаты.
  • limit: Этот параметр определяет максимальное количество записей, которые будут возвращены в ответе.

Чтобы получить значения skip и limit исходя из номера страницы и длины страницы, можно использовать следующие формулы:

  1. limit: Это фиксированное значение, которое определяет количество записей на одной странице. Например, если длина страницы составляет 10 записей, то limit будет равен 10.

  2. skip: Для расчета значения skip можно использовать следующую формулу:

skip = (номер страницы - 1) * limit

Где: - номер страницы — это номер страницы, которую вы хотите получить (например, 1, 2, 3 и т.д.). - limit — количество записей на странице.

Например, если вы хотите получить данные для 3-й страницы и длина страницы составляет 10 записей: - номер страницы = 3 - limit = 10

Тогда skip будет рассчитан следующим образом: skip = (3 - 1) * 10 = 20 Таким образом, для запроса данных на 3-й странице с длиной страницы 10, параметры будут следующими: - skip = 20 - limit = 10

Фильтрация результатов поиска

Фильтрация результатов поиска осуществляется через GET-параметр params - могут быть применены условие равенства:


{"field":"vendor","condition":"in","options":["Cool vendor","Bad vendor"]}

и вхождения в диапазон:


{"field":"price","min":"200","max":"1000","condition":"range"}

Данные условия могут быть комбинированы в формате:


params=[{"field":"price","min":"200","max":"1000","condition":"range"},{"field":"vendor","condition":"in","options":["Cool vendor","Bad Vendor"]}]

Подобные фильтры могут быть применены к любому параметру товара, передаваемому в каталоге. Для фильтрации параметра из фида в качестве field нужно использовать его название. Например если в фиде парамтер передается как <param name="цвет">красный</param>

То для фильтрации нужно передать


{"field":"цвет","condition":"in","options":["красный"]}

Сортировка

В методе /search допустимо использовать сортировку результатов.

Допустимые значения get-параметров sortBy и sortDest для сортировки результатов поиска метода /search:

&sortBy=price&sortDest=DESC - для фильтрации по цене (сначала дорогие)

&sortBy=price&sortDest=ASC - для фильтрации по цене (сначала дешевые)

&sortBy=available&sortDest=DESC - для фильтрации по наличию

&sortBy=_score&sortDest=DESC - для фильтрации по популярности &sortBy=_score&sortDest=ASC – не имеет смысла. Рекомендуем, не использовать данное сочетание параметров

Дополнительно можно сортировать по кастомным полям, но для этого нужно вносить изменения в Личном кабинете SearchBooster на странице Настройки в в Разделе "Формула сортировки поиска". После внесения изменений в формулу сортировки поиска, в методе /search можно передавать наименование поля в get-параметре sortBy. При наличии затруднений обращайтесь к своему аккаунт-менеджеру.

Предварительные результаты поиска (поисковые подсказки)

Подсказки могут быть получены при помощи метода /completions.

Пример запроса:

https://api.searchbooster.net/api/v2/ca8fc618-9ee9-48f1-b9b6-92e810424297/completions?query=соб&completionSettings={"orders":["popular","categories","brands","history","suggestions","special_offers","offers"],"totalCompletionCount":6,"limits":{"brands":1,"offers":1,"history":1,"popular":1,"categories":1,"suggestions":1,"special_offers":1}}

Описание параметров запроса: query - поисковый запрос - обязательный параметр completionSettings - настройки вывода подсказок

Параметр completionSettings представляет собой объект JSON, который включает следующие поля:

  • orders (обязательно): Массив строк, который указывает порядок, в котором следует возвращать предложения для автозаполнения. Возможные значения: "popular" (популярные), "categories" (категории), "brands" (бренды), "history" (история), "suggestions" (предложения), "special_offers" (специальные предложения) и "offers" (предложения).
  • totalCompletionCount (обязательно): Общее количество предложений для автозаполнения, которые следует вернуть.
  • limits (обязательно): Объект JSON, который указывает максимальное количество предложений для автозаполнения, которые следует вернуть для каждого типа. Возможные типы: "brands" (бренды), "offers" (предложения), "history" (история), "popular" (популярные), "categories" (категории), "suggestions" (предложения) и "special_offers" (специальные предложения).

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

{
  "searchBox": [
    {
      "text": {
        "html": "Самоедская \u003Cstrong\u003Eсоб\u003C/strong\u003Eака",
        "value": "Самоедская собака"
      },
      "label": "categories",
      "id": "8145",
      "count": 218,
      "search": {
        "query": "",
        "categoryId": "8145"
      },
      "snippet": "",
      "offer": {
        "available": false,
        "offerLabelsTyped": null
      }
    }
  ],
  "offers": [
    {
      "available": true,
      "id": "110166",
      "score": 28.942768,
      "name": "Самоедская собака 1",
      "url": "https://demo.searchbooster.io/product/самоедская-собака-1/",
      "price": 960,
      "oldPrice": 1200,
      "currency": "RUR",
      "pictures": [
        "https://slc.searchbooster.io/fOqSfd1rCKB-lx5EaXkh-LdhS9-MdvRhP66V6NPBGbo/rs:fit:300:450:0:sm/aHR0cHM6Ly9kZW1vLnNlYXJjaGJvb3N0ZXIuaW8vd3AtY29udGVudC91cGxvYWRzL24wMjExMTg4OV8xOTg0LmpwZw.jpeg"
      ],
      "category": {
        "id": "8145",
        "name": "Самоедская собака"
      },
      "categories": [
        {
          "id": "8145",
          "name": "Самоедская собака"
        }
      ],
      "isPickup": false,
      "isDelivery": false,
      "isPreorder": false
    }
  ],
  "tips": [],
  "meta": {

  },
  "hits": 0
}

Поиск по фото

Для поиска по фото следует использовать метод /search, но отсылать его как POST, дополнительно указав фото в теле запроса. Для кодирования фото необходимо использовать формат data:image/jpeg и передовать изображение в base64

{
  "image": "data:image/jpeg;base64,....."
}

Пример запроса

curl 'https://api.searchbooster.net/api/ca8fc618-9ee9-48f1-b9b6-92e810424297/search?skip=0&limit=24' \
  -H 'accept: */*' \
  -H 'content-type: text/plain;charset=UTF-8' \
  --data-raw '{"image":"data:image/jpeg;base64,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"}'