Документация API каталога автомобилей

Начните с небольшой страницы каталога. Запрос возвращает data с автомобилями, pagination с курсором и время формирования generated_at.

1. Запросите GET /cars с limit=3.
2. Возьмите id из ответа и запросите GET /cars/{car_id} для полной карточки.
3. Для продолжения передайте pagination.next_cursor в следующий запрос с теми же фильтрами.

Все методы ниже выполняют чтение. В публичном контуре не нужны регистрация и API-ключ.

Примеры JavaScript рассчитаны на Node.js 18+ и выполнение на вашем сервере. Python использует стандартную библиотеку.

Сначала получите фасеты — доступные варианты и диапазоны. Пользователю показывайте label, в запрос передавайте value.

• q — текстовый поиск.
• source_country — JP, KR или CN.
• manufacturer и model можно повторять в URL для множественного выбора.
• engine_type принимает значения через запятую: gasoline,hybrid.
• sort — сортировка по цене, году или пробегу. Точные значения — в параметрах каталога.

Выбор комплектации

После выбора одной марки и одной модели запросите GET /cars/trims. Значение trims[].value передайте в trim у каталога и фасетов.

При смене марки или модели сбрасывайте выбранную комплектацию. В запросах фасетов и каталога сохраняйте одинаковый набор фильтров.

price_min/max — цена объявления в валюте источника. landed_price_min/max — полная или предварительная стоимость во Владивостоке в рублях; частичная сумма в этот фильтр не входит.

limit задаёт размер страницы: от 1 до 100. Продолжение находится в pagination.next_cursor, наличие следующей страницы — в pagination.has_more.

1. Первый запрос отправляйте без cursor.
2. Передавайте полученный курсор без изменения вместе с прежними фильтрами и сортировкой.
3. Заканчивайте обход при has_more=false или пустом next_cursor.

После изменения фильтров или сортировки начинайте с первой страницы. Курсор — непрозрачная строка; разбирать или конструировать его самостоятельно не нужно.

Параметры page и read_version предназначены для отдельно разрешённого партнёрского режима. Публичная интеграция использует cursor; смешивание режимов приводит к ошибке.

Каталог возвращает компактную карточку. Метод GET /cars/{car_id} дополняет её фотографиями, оснащением, характеристиками и статьями расчёта.

identity

Марка, модель, название и комплектация

listing

Год, пробег, цена объявления, валюта и статус продажи

specs

Кузов, двигатель, мощность, привод и другие характеристики

media

Фотографии и панорамы при наличии

pricing

Стоимость во Владивостоке и полнота расчёта

source

Страна и площадка-источник

links

Ссылка на страницу автомобиля

null означает отсутствие значения, а не ноль. Не все характеристики и медиа присутствуют у каждого объявления.

Подтверждённо проданные объявления могут сохраняться с прежним id и listing.sell_status=sold. Показывайте статус продажи; успешный HTTP-ответ сам по себе не подтверждает доступность автомобиля.

{
  "id": 2309234,
  "identity": {
    "manufacturer": "Daihatsu",
    "model": "Mira Cocoa",
    "title": "Daihatsu Mira Cocoa",
    "trim": "L"
  },
  "listing": {
    "year": 2014,
    "mileage_km": 127000,
    "price": 348000,
    "currency": "JPY",
    "sell_status": "active"
  },
  "specs": {
    "vehicle_type": "hatchback"
  },
  "media": {
    "main_photo": "https://carhubauto.ru/api/v2/cars/2309234/photo"
  },
  "pricing": {
    "presentation": {
      "amount_rub": 629773,
      "kind": "estimated",
      "label": "Предварительная цена во Владивостоке"
    }
  },
  "source": {
    "country": "JP"
  },
  "links": {
    "carhub": "https://carhubauto.ru/car/2309234/"
  }
}

Срез публичного ответа от 19 октября 2026. Значения и наличие могут измениться. Полная схема: CarSummary и CarDetail.

Сначала проверяйте HTTP-статус и Content-Type. Ошибки приложения содержат detail; защитный ответ сервера может иметь другой формат.

Публичный лимит приложения — 120 запросов в минуту с одного IP на метод. Дополнительные ограничения сервера могут сработать раньше. При 429 учитывайте Retry-After, если заголовок присутствует.

Повторяйте временные ошибки с увеличением паузы и ограничением числа попыток. Сохраняйте последнюю успешную выдачу и используйте кеширование. Ошибки параметров требуют исправления запроса.

// 404: автомобиль не найден
{ "detail": "Car not found" }

// 422: limit превышает допустимое значение
{
  "detail": [{
    "type": "less_than_equal",
    "loc": ["query", "limit"],
    "msg": "Input should be less than or equal to 100",
    "input": "500"
  }]
}