API docs by Redocly

AnyQuery API (1.1.0)

Download OpenAPI specification:

Документация по API сервиса AnyQuery.

Серверы по продуктам:

  • Поиск: https://sort.diginetica.net
  • Автоподсказки: https://autocomplete.diginetica.net
  • Рекомендации: https://recs.diginetica.net
  • Поиск по картинкам: https://api.diginetica.net
  • Трекинг: https://tracking-app.diginetica.net

Рекомендуемые клиентские таймауты:

  • /search — 2000 мс
  • /autocomplete — 300 мс
  • /recs — 1000 мс
  • /v1/imagesearch/search — 30 секунд

Таймауты носят рекомендательный характер. При превышении таймаута клиент должен показывать fallback-контент.

Search

Поиск товаров с ML-ранжированием.

Базовый URL: https://sort.diginetica.net

Поиск товаров

Основной эндпоинт для получения ранжированных результатов поиска. Возвращает список товаров, фасеты (фильтры) и мета-информацию о запросе.

query Parameters
st
required
string
Example: st=телевизор

Пользовательский поисковый запрос.

apiKey
required
string
Example: apiKey=your_api_key_here

Ключ доступа для идентификации канала продаж. Предоставляется командой Diginetica.

strategy
string
Example: strategy=advanced_xname,zero_queries

Стратегия ML-ранжирования. По умолчанию берётся из серверной конфигурации сайта; если клиент передаёт значение, оно может быть переопределено серверной конфигурацией. Предоставляется командой Diginetica.

size
integer [ 1 .. 2000 ]
Default: 400
Example: size=20

Количество товаров в ответе.

  • Максимум 400 при fullData=true
  • Максимум 2000 при fullData=false
offset
integer >= 0
Default: 0

Количество товаров для пропуска (пагинация).

fullData
boolean
Default: false

Включить расширенную информацию о товарах.

withCorrection
boolean
Default: false
Example: withCorrection=true

Возвращать исправленный вариант запроса.

useCompletion
boolean
Default: false

Дописывать часть запроса до предиктивно выбранного полного слова.

withFacets
boolean
Default: false
Example: withFacets=true

Включить в ответ фасеты (фильтры).

treeFacets
boolean
Default: false
Example: treeFacets=true

Формат иерархии фасетов категорий:

  • true — дерево
  • false — плоский список
filter
string
Examples:
  • filter=price:2;100 - По цене
  • filter=categories:12967 - По категории
  • filter=brands:Samsung - По бренду
  • filter=Цвет:алый - По атрибуту

Фильтрация результатов. Параметр может повторяться.

Синтаксис:

  • filter=<тип>:<значение>
  • filter=<тип>:<знач1>;<знач2> — OR
  • filter=<тип>:<знач1>&filter=<тип>:<знач2> — AND

Встроенные типы: price, categories, brands, <НазваниеАтрибута>

showUnavailable
boolean
Default: false
Example: showUnavailable=true

Показывать товары, недоступные для покупки.

unavailableMultiplier
number <float> [ 0 .. 1 ]
Default: 0.2
Example: unavailableMultiplier=0.2

Множитель скоринга для недоступных товаров (0–1).

sort
string
Default: "DEFAULT"
Enum: "DEFAULT" "PRICE_ASC" "PRICE_DESC"
Example: sort=DEFAULT

Сортировка:

  • DEFAULT — по релевантности
  • PRICE_ASC — цена по возрастанию
  • PRICE_DESC — цена по убыванию
regionId
string
Default: "global"
Example: regionId=global

Идентификатор региона / фида. По умолчанию: global.

withSku
boolean
Default: false

Группировать товары в мультикарточки по полю group_id из фида.

productId
string

ID товара-якоря (для контекстных стратегий ранжирования).

useCategoryPrediction
boolean

Включить предсказание категории по запросу (буст товаров из предсказанной категории).

exceptionIds
string
Example: exceptionIds=TV-001,TV-002

ID товаров, которые нужно исключить из выдачи (через запятую).

modelName
string

Имя ML-модели ранжирования. Обычно берётся из серверной конфигурации сайта.

Responses

Response samples

Content type
application/json
{
  • "query": "телевизор",
  • "correction": "телевизор",
  • "totalHits": 142,
  • "zeroQueries": false,
  • "redirectUrl": null,
  • "redirectMobileUrl": null,
  • "products": [],
  • "facets": [
    ],
  • "selectedFacets": [ ]
}

Autocomplete

Автоподсказки в поисковой строке.

Базовый URL: https://autocomplete.diginetica.net

При вводе подряд нескольких символов клиент обычно отправляет несколько запросов параллельно — порядок возврата ответов не гарантирован. На стороне клиента необходимо проверять актуальность каждого ответа относительно текущего значения строки ввода.

Автоподсказки

Возвращает поисковые подсказки, товары, категории, бренды и контентные ссылки.

Рекомендации:

  • При фокусе на строке без текста — запрос с пустым st.
  • При вводе — запрос на каждый символ.
  • Проверять актуальность каждого ответа (асинхронность).

При серверной интеграции значение поля correction из этого API обязательно передавать в параметр st запроса к Search API.

query Parameters
st
required
string
Example: st=кросовк

Поисковый запрос. При пустом значении — топ-10 просматриваемых товаров.

apiKey
required
string
Example: apiKey=your_api_key_here

Ключ API клиента.

strategy
string
Default: "simple"
Example: strategy=advanced_xname,zero_queries

Список стратегий через запятую. По умолчанию — simple. Может переопределяться серверной конфигурацией сайта. Предоставляется командой Diginetica.

productsSize
integer [ 1 .. 100 ]
Default: 10
Example: productsSize=10

Количество товаров в ответе. По умолчанию: 10. Максимум: 100.

regionId
string
Default: "global"
Example: regionId=global

ID региона / фида. По умолчанию: global.

forIs
boolean
Default: false

Управляет поиском категорий по названию.

  • false — категории ищутся по названию
  • true — поиск категорий по названию отключён
showUnavailable
boolean
Default: false

Показывать недоступные товары.

withContent
boolean
Default: false

Включить ссылки на контентные страницы.

withSku
boolean
Default: false

Отображать группы товаров (мультикарточки).

productId
string

ID товара-якоря (используется некоторыми стратегиями для контекстных подсказок).

shuffle
boolean
Default: true

Перемешивать выдачу.

contentsSize
integer >= 0
Default: 10

Количество контентных ссылок в ответе.

unavailableMultiplier
number <float> [ 0 .. 1 ]
Default: 0.2

Множитель скоринга для недоступных товаров (0–1). Может переопределяться серверной конфигурацией.

useCompletion
boolean
Default: true

Дописывать часть запроса до предиктивно выбранного полного слова.

Responses

Response samples

Content type
application/json
{}

Recommendations

Блоки персональных рекомендаций товаров.

Базовый URL: https://recs.diginetica.net

Рекомендуемый клиентский таймаут: 1000 мс. При превышении клиент должен показывать fallback-контент.

Параметр placements задаёт одно или несколько мест размещения (через |). Конкретные значения предоставляются командой Diginetica (например, home_page, product_page).

Параметр productId — ID товара-якоря (используется для блоков на странице товара). Параметр categoryId — ID категории-якоря (используется для блоков на странице категории).

Получить блоки рекомендаций

Возвращает один или несколько ранжированных блоков рекомендованных товаров — по одному на каждый запрошенный placement.

Типичные значения placements (предоставляются командой Diginetica):

Страница Пример placement Якорь
Главная home_page —
Карточка товара product_page productId
Корзина cart_page — (используется userHistory)
Категория category_page categoryId
Нулевая выдача zero_results_page —

Несколько плейсментов можно запросить одной строкой через |: placements=home_page|product_page.

query Parameters
apiKey
required
string
Example: apiKey=your_api_key_here

Ключ API клиента.

placements
required
string
Examples:
  • placements=home_page - Один плейсмент
  • placements=home_page|product_page - Несколько плейсментов

Один или несколько идентификаторов мест размещения, разделённых |. Конкретные значения предоставляются командой Diginetica.

productId
string
Example: productId=100234

ID товара-якоря для блоков на странице карточки товара.

categoryId
string
Example: categoryId=1012

ID категории-якоря для блоков на странице категории.

regionId
string
Default: "global"
Example: regionId=msk

ID региона / фида.

fullData
boolean
Default: false

Возвращать расширенные данные о товарах (атрибуты, категории, SKU).

userHistory
string

История взаимодействия пользователя (формат предоставляется командой Diginetica). Используется для персонализации.

showUnavailable
boolean
Default: false

Если true — недоступные товары не отфильтровываются из ответа.

page
integer >= 0

Номер страницы (пагинация). Используется вместе с size.

size
integer >= 1
Example: size=10

Количество товаров в каждом блоке.

Responses

Response samples

Content type
application/json
Example
{
  • "placements": [
    ],
  • "status": "ok",
  • "message": ""
}

ImageSearch

Поиск товаров по изображению.

Базовый URL: https://api.diginetica.net

Принимает изображение в формате multipart/form-data.

Рекомендуемые параметры изображения: форматы jpg, jpeg, png, webp; длинная сторона ~1024px. Сервер сжимает изображения, но рекомендуется выполнять предварительное сжатие на клиентской стороне.

Максимальный размер файла: 10 MB. Запросы с файлом большего размера отклоняются.

Серверный таймаут запроса: 30 секунд. Клиентский таймаут стоит выставлять с запасом.

⚠️ API-ключ передавать только через серверную сторону. Не вставлять в фронтенд-код.

Поиск по изображению

Принимает изображение в формате multipart/form-data и возвращает список визуально похожих товаров.

Рекомендуемые параметры изображения: форматы jpg, jpeg, png, webp; длинная сторона ~1024px. Сервер сжимает изображения, но рекомендуется выполнять предварительное сжатие на клиентской стороне.

Максимальный размер файла: 10 MB. Запросы с файлом большего размера отклоняются.

Процесс интеграции:

  1. Пользователь загружает фото или кликает «Найти похожие» на карточке товара.
  2. Фронтенд передаёт изображение на ваш сервер; сервер выполняет сжатие/валидацию.
  3. Ваш сервер формирует multipart/form-data и отправляет POST-запрос в API.
  4. API возвращает результаты; сервер отдаёт их фронтенду.

⚠️ API-ключ передавать только через серверную сторону. Не вставлять в фронтенд-код.

Серверный таймаут запроса: 30 секунд. Клиентский таймаут стоит выставлять с запасом.

query Parameters
apiKey
required
string
Example: apiKey=your_api_key_here

Ключ API клиента. Хранить только на сервере.

Request Body schema: multipart/form-data
required
image
required
string <binary>

Изображение файлом. Рекомендуемые форматы: jpg, jpeg, png, webp. Рекомендуемый размер: 1024px по длинной стороне.

productsSize
integer >= 1
Default: 30

Желаемое количество товаров в ответе.

offset
integer >= 0
Default: 0

Сдвиг (пагинация).

showUnavailable
boolean
Default: false

Управляет показом недоступных товаров.

  • true — недоступные товары будут в результатах
  • false — недоступные товары скрываются
deboostUnavailable
boolean
Default: true

Смещение недоступных товаров вниз. Работает только при showUnavailable=true.

  • true — недоступные показываются после всех доступных
  • false — недоступные показываются вперемешку с доступными
regionId
string
Default: "global"

ID регионального фида.

Responses

Request samples

Content type
multipart/form-data
{
  "image": "picture.jpg",
  "productsSize": 20,
  "showUnavailable": false,
  "deboostUnavailable": true,
  "regionId": "25"
}

Response samples

Content type
application/json
{}

Tracking

Трекинг поведения пользователей.

Базовый URL: https://tracking-app.diginetica.net

Публичный контракт — POST на /event с одним событием в JSON-теле. Тестовый стенд: https://tracking-dev.diginetica.net/event (события изолированы и не уходят в продакшен).

Заголовки: Content-Type: application/json;charset=UTF-8

Ограничения: одно событие на запрос. На стороне инфраструктуры может действовать rate-limit.

Коды ответов:

  • 200 — событие принято
  • 400 — ошибка валидации (отсутствует обязательное поле, неверный apiKey)
  • 403 — сайт заблокирован
  • 500 — внутренняя ошибка сервера
  • 504 — таймаут на стороне балансировщика

Отправка трекингового события

Универсальный эндпоинт для отправки всех типов событий.

Тип события определяется полем eventType в теле запроса.

Поддерживаемые типы событий:

Общие:

  • HOME_PAGE_VIEW — просмотр главной страницы
  • PRODUCT_VIEW — просмотр карточки товара
  • SEARCH_EVENT — страница результатов поиска
  • CART_VIEW — просмотр корзины
  • ORDER_SUCCESS — успешный заказ
  • BRAND_PAGE_VIEW — просмотр страницы бренда (опционально)
  • CATEGORY_VIEW — просмотр страницы категории (опционально)

После интеграции автоподсказок:

  • AUTOCOMPLETE_CLICK — клик по подсказке
  • AQ_SYNONYM_CLICK — клик по уточнению в результатах поиска

После интеграции рекомендаций:

  • WIDGET_VIEW (RECS_RENDER, RECS_VIEW) — отрисовка / просмотр блока
  • WIDGET_CLICK (RECS_CLICK, RECS_FAVORITE_CLICK, RECS_COMPARE_CLICK) — клик в блоке
  • CART_ADD_EVENT — добавление в корзину из блока рекомендаций

После интеграции поиска по картинкам:

  • WIDGET_VIEW / WIDGET_CLICK (IMAGE_SEARCH) — действия с поиском по фото
  • CART_ADD_EVENT — добавление в корзину из результатов поиска по фото
Request Body schema: application/json
required
eventType
required
string
Enum: "HOME_PAGE_VIEW" "PRODUCT_VIEW" "SEARCH_EVENT" "CART_VIEW" "ORDER_SUCCESS" "BRAND_PAGE_VIEW" "CATEGORY_VIEW" "AUTOCOMPLETE_CLICK" "AQ_SYNONYM_CLICK" "WIDGET_VIEW" "WIDGET_CLICK" "CART_ADD_EVENT"

Тип события.

apiKey
required
string

Ключ клиента.

sessionId
required
string

ID сессии. Обновляется после 30 мин бездействия.

userGUID
required
string <= 64 characters

Долговременный ID пользователя. Формат: 0:<TIMESTAMP_base36>:<UUID>.

userId
string

ID залогиненного пользователя. Передавать только при активной авторизации.

regionId
string

ID региона (регистр важен).

viewGUID
string

ID просмотра страницы. Одинаковый для всех событий страницы.

location
string <uri>

URL текущей страницы.

referer
string <uri>

URL предыдущей страницы.

channel
required
string
Enum: "WEB" "WEB_MOBILE" "MOBILE_APP"
productId
string

Offer ID товара.

productName
string

Название товара.

availability
boolean

Доступность товара (PRODUCT_VIEW).

isFromRedirect
string

Попал через редирект из поиска. Передавать как строку ("true" / "false").

searchTerm
string

Запрос после исправления (значение correction из API).

originalSearchTerm
string

Оригинальный запрос пользователя.

pageProducts
Array of strings

Offer ID товаров на странице.

pageNumber
integer <int32>

Номер страницы.

isZeroQuery
string

Значение zeroQueries из ответа Search API. Передавать как строку ("true" / "false").

anyQueryWorked
string

Было ли исправление запроса (originalSearchTerm !== searchTerm). Передавать как строку ("true" / "false").

cartId
string

ID корзины. Сквозной между CART_VIEW и ORDER_SUCCESS.

subtotal
string

Сумма товаров.

total
string

Итоговая сумма.

orderId
string

Номер заказа.

Array of objects (CartItem)
brandName
string

Название бренда (BRAND_PAGE_VIEW).

categoryName
string

Название категории (CATEGORY_VIEW).

categoryId
string

ID категории из фида.

breadcrumbs
Array of strings

Хлебные крошки (без «Главная» и «Каталог»).

autocompleteItem
string

Текст кликнутой подсказки.

autocompleteItemType
string
Enum: "queries" "products" "categories" "brands" "history" "taps"
anyQuerySynonymClicked
string

Выбранное уточнение (AQ_SYNONYM_CLICK).

anyQuerySynonyms
Array of strings
widgetType
string
Enum: "RECS_RENDER" "RECS_VIEW" "RECS_CLICK" "RECS_FAVORITE_CLICK" "RECS_COMPARE_CLICK" "IMAGE_SEARCH"
strategy
string

Строка параметров блока через |.

seed
string

ID товаров-якорей через |.

position
integer or null

Позиция товара в блоке (с 1).

price
string

Цена товара (CART_ADD_EVENT).

sku
string

Артикул или служебная строка.

Responses

Request samples

Content type
application/json
Example
{
  • "eventType": "HOME_PAGE_VIEW",
  • "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "location": "http://example.com/home",
  • "apiKey": "APIKEY",
  • "userGUID": "0:kzmrfk1k:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "regionId": "msk",
  • "viewGUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "channel": "WEB"
}