Интеграция с использованием 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 исходя из номера страницы и длины страницы, можно использовать следующие формулы:
-
limit: Это фиксированное значение, которое определяет количество записей на одной странице. Например, если длина страницы составляет 10 записей, то limit будет равен 10.
-
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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"}'