Синтаксис фильтров поиска

Фильтры — это параметры запроса в формате PHP с квадратными скобками. Одни и те же фильтры работают в /search и /search/count; /cars принимает domains[] и is_leasing.

• Категориальные фильтры принимают числовые ID. Все ID см. в разделе Значения перечислений.
• currency влияет только на фильтрацию и сортировку по цене. Цены объявлений всегда возвращаются в исходной валюте.
• Для точного VIN используйте /cars/vin/{vin}. Фильтр vin в /search ищет частичное совпадение.
• Не передавайте фильтры, которые не используете. Пустые значения проходят валидацию и могут вернуть 422.

is_auction принимает true, false, 1 или 0 на /search, /search/count и /cars. False включает false, null и отсутствующие поля. Без параметра фильтр отключен; пустое или неверное значение возвращает 422. is_auction и is_leasing должны совпасть в одном активном объявлении доступного/выбранного источника. Другие объявления могут остаться в listings[]. Для /cars задайте фильтр в первом запросе и следуйте next_url без изменений; добавление или изменение фильтра в scroll-сессии либо явное значение при утрате кеша возвращает 422. sort=auction_nearest требует auction_at >= now; передавайте ту же сортировку в /search/count.

Фильтр по типу транспорта и конфигурации

vehicle_type=automobile / 1 — по умолчанию; motorcycle / 2 выбирает мотоциклы в /search, /search/count и /cars. В справочниках используйте тот же тип.

Полная вложенность: brands[] → models[] → generations[] → variants[] / trims[]. У каждого объекта бренда, модели и поколения обязателен id. Между соседями и значениями в списках variants/trims — ИЛИ; между условиями одной ветки — И. Отсутствующий или пустой дочерний список означает любых потомков. В каждом массиве до 100 элементов. Неизвестные или несовместимые ID дают пустой результат; неверный формат — 422.

Прежний brands[0][models][]=573 работает. Для потомков используйте brands[0][models][0][id]=573. Уберите прежнее поле добавления ID перед вводом объектов моделей этого бренда, иначе PHP перезапишет индекс 0.

vehicle_type=motorcycle&brands[0][id]=101&brands[0][models][0][id]=201&brands[0][models][0][generations][0][id]=301&brands[0][models][0][generations][0][variants][]=501&brands[0][models][0][generations][0][trims][]=401

ID вымышленные: замените их значениями из справочников. Для конкретных пар variant/trim используйте отдельные ветки поколений.

В ответах появились vehicle_type, generation_id, variant_id и trim_id; отсутствующие необязательные ID равны null. Поля участвуют в hash. Поиск использует только сохранённые ID машины: без нормализованного ID машина не соответствует выбранному условию.

В /cars тип и вся иерархия фиксируются на время прокрутки. Следуйте next_url без изменений или передавайте только scroll_id. Можно менять порядок эквивалентных фильтров; изменение условий или явные фильтры при потере состояния дают 422. Начните новую прокрутку. Старые курсоры без новых параметров сохраняют прежний запрос.

Дополнительные поля листингов

Загрузите /listing-fields после проверки ключа. Определения, ограничения, операторы и пояснения источников относятся только к этому ключу и выбранным доменам.

Для строк: eq, in, exists. Для чисел и дат также gt, gte, lt, lte. Для boolean: eq или exists. Выберите eq, in, exists либо диапазон; exists используется отдельно. До 20 полей и 100 значений в in.

Все условия, выбранные домены и активность должны совпасть в одном листинге. Ноль и false — настоящие значения. Для массива подходит совпадающий элемент. Неизвестные или недоступные поля/операторы возвращают 422.

Фильтровать можно только filterable-поля. Индексируемые значения находятся в listings[].custom_fields, остальные — в listings[].source_data. Публикация включает фильтры; значения заполняются при следующих штатных импортах. Старые документы отдельно не обновляются.

В /cars условия сохраняются на весь scroll. Несовместимое определение поля или потеря состояния фильтра требуют нового scroll. Сортировки и агрегации по этим полям не поддерживаются.

В примерах замените FIELD_KEY ключом из доступного вам каталога. Для денежных сравнений также укажите валюту самого листинга; пересчёт Buy Now здесь не применяется.

Исторические рыночные оценки источника — справочные неиндексируемые значения. Они описывают сопоставимые продажи, а не цену, ставку или резерв данного объявления. Проверяйте описание поля, критерии сравнения и дату расчёта; валюту листинга подставлять нельзя. Зарегистрированные числовые поля могут быть null, если оценки нет.

custom_fields[FIELD_KEY][gte]=2
custom_fields[FIELD_KEY][in][]=a&custom_fields[FIELD_KEY][in][]=b
custom_fields[FIELD_KEY][eq]=false
custom_fields[FIELD_KEY][lte]=15000&custom_fields[FIELD_KEY][currency]=cad