CarHub API v2

API каталога автомобилей

Автомобили с торговых площадок Кореи, Японии и Китая: характеристики, фотографии, 360-панорамы и готовый расчет стоимости во Владивостоке. API отдает JSON, работает только на чтение и не требует ключа для публичных endpoints.

Base URLhttps://carhubauto.ru/api/v2

OpenAPI-спека

Быстрый старт

Первый запрос

Запросите страницу каталога — этого достаточно, чтобы получить автомобили с фото, характеристиками и итоговой ценой. Регистрация не нужна.

1
GET /cars возвращает страницу каталога и курсор pagination.next_cursor.
2
Передайте курсор в параметре cursor следующего запроса — получите продолжение выдачи.
3
По id автомобиля запросите GET /cars/{id} — полную карточку с расчетом цены и всеми фото.

Все примеры на странице рабочие: скопируйте — и они выполнятся против боевого API.

curl 'https://carhubauto.ru/api/v2/cars?limit=3&photo_only=true'

const response = await fetch(
  "https://carhubauto.ru/api/v2/cars?limit=3&photo_only=true"
);
const page = await response.json();

for (const car of page.data) {
  console.log(car.identity.title, car.pricing?.total_rub);
}

import requests

page = requests.get(
    "https://carhubauto.ru/api/v2/cars",
    params={"limit": 3, "photo_only": True},
    timeout=10,
).json()

for car in page["data"]:
    print(car["identity"]["title"], car["pricing"]["total_rub"])

Ответ · сокращен

{
  "data": [
    {
      "id": 943576,
      "identity": {
        "manufacturer": "BMW",
        "model": "X3",
        "title": "BMW X3",
        "trim": "xDrive20d M"
      },
      "listing": {
        "year": 2021,
        "mileage_km": 35000,
        "price": 3880000,
        "currency": "JPY",
        "sell_status": "active"
      },
      "specs": {
        "vehicle_type": "suv",
        "fuel_type": "Дизель",
        "drive_type": "AWD",
        "engine_power_hp": 181
      },
      "media": {
        "main_photo": "…/api/v2/cars/943576/photo",
        "has_panorama": true
      },
      "pricing": {
        "market_label": "Япония",
        "total_rub": 4617233,
        "listing_rub": 1826056
      },
      "source": { "country": "JP", "name": "Aucnet.jp" },
      "links": { "carhub": "…/car/943576/" }
    }
  ],
  "pagination": {
    "limit": 3,
    "next_cursor": "eyJ2IjoxLCJzb3J0Ijoi…",
    "has_more": true
  }
}

Аутентификация

Публичный и партнерский доступ

Публичный доступ

Все endpoints этой документации доступны без ключа и работают только на чтение. Действует ограничение частоты запросов — см. раздел Ошибки и лимиты.

Подходит для сайтов, витрин и прототипов: каталог, карточки, фасеты, справочник марок и курсы валют.

Партнерский доступ

Для интеграций с повышенными лимитами существует партнерский контур/api/v2/partner/… с ключом в заголовке X-CarHub-API-Key. Только запросы сервер-сервер: не размещайте ключ в браузерном коде и не передавайте его в URL. Доступ выдается по договоренности.

Запрос с ключом

curl 'https://carhubauto.ru/api/v2/partner/cars?limit=50' \
  -H 'X-CarHub-API-Key: <ключ>'

Данные

Как устроены данные

Карточка автомобиля

Каждый автомобиль — объект с семью блоками. В каталоге приходит компактная версия карточки, в GET /cars/{id} — полная: с постатейной расшифровкой цены, всеми фотографиями и оснащением комплектации.

Идентификатор id стабилен — по нему можно строить постоянные ссылки и синхронизировать данные на своей стороне.

Структура карточки

{
  "id": 943576,
  "identity": { "марка, модель, комплектация" },
  "listing":  { "год, пробег, цена, статус" },
  "specs":    { "кузов, топливо, привод, мощность" },
  "media":    { "фото и 360-панорамы" },
  "pricing":  { "расчет стоимости во Владивостоке" },
  "source":   { "площадка-источник" },
  "links":    { "страница на CarHub" }
}

Расчет стоимости

pricing.total_rub — итоговая стоимость автомобиля во Владивостоке: цена объявления, расходы страны покупки, фрахт, таможенная пошлина, утилизационный сбор и оформление.

В детальной карточке массив steps раскрывает расчет постатейно — суммы статей дают итог. Расчет обновляется автоматически при изменении курсов; момент курса зафиксирован в rates_fetched_at.

Блок pricing в карточке

"pricing": {
  "market_label": "Япония",
  "total_rub": 4617233,
  "listing_rub": 1826056,
  "customs_rub": 485237,
  "recycling_rub": 1642000,
  "currency_rate": 0.470633,
  "eur_rate": 87.3511,
  "rates_fetched_at": "2026-07-09T08:02:03Z",
  "steps": [
    {
      "key": "listing",
      "label": "Стоимость на аукционе",
      "amount_rub": 1826056,
      "amount_original": 3880000.0,
      "currency": "JPY"
    },
    {
      "key": "japan_local",
      "label": "Расходы по Японии",
      "amount_rub": 340854,
      "bullets": [
        "комиссия аукциона",
        "логистика внутри Японии",
        "погрузка на судно"
      ]
    }
  ]
}

Курсы валют

GET /currency/rates возвращает курсы USD, EUR, CNY, JPY и KRW к рублю по данным ЦБ РФ, нормализованные к цене за единицу валюты.

Это те же курсы, по которым считается pricing: по курсу валюты объявления пересчитывается цена, по курсу EUR — таможенная пошлина.

Ответ /currency/rates

{
  "data": {
    "source": "cbr",
    "nominal_date": "2026-07-09",
    "fetched_at": "2026-07-09T09:04:02Z",
    "usd_rub": 76.4026,
    "eur_rub": 87.3511,
    "cny_rub": 11.2219,
    "jpy_rub": 0.470633,
    "krw_rub": 0.050048
  }
}

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

Все URL медиа абсолютные — используйте их как есть. media.main_photoможет вести на фотопрокси CarHub /cars/{id}/photo: он отдает изображение даже когда площадка-источник недоступна из браузера клиента.

В детальной карточке фото разделены на listing_photos (из объявления) и configuration_photos (студийные фото комплектации), аpanoramas содержит 360-виды интерьера и экстерьера. Логотипы марок — в поле logo_url ответа GET /catalog/brands. Медиа можно кешировать на стороне клиента.

Блок media в карточке

"media": {
  "main_photo": "…/api/v2/cars/943576/photo",
  "has_panorama": true,
  "listing_photos": [
    {
      "url": "…/api/v2/cars/943576/photo",
      "label": "Основное фото",
      "type": "photo"
    }
  ],
  "configuration_photos": [
    {
      "url": "https://s3.twcstorage.ru/…/main.jpg",
      "label": "Главное",
      "type": "catalog_photo"
    },
    {
      "url": "https://s3.twcstorage.ru/…/saloon.jpg",
      "label": "Салон спереди",
      "type": "catalog_photo"
    }
  ],
  "panoramas": [
    {
      "url": "https://pano.autohome.com.cn/car/pano/51645",
      "label": "Панорама интерьера",
      "type": "interior_panorama"
    }
  ]
}

Фильтры, поиск и пагинация

Каталог листается курсором: сервер возвращает pagination.next_cursor, клиент передает его в параметре cursor. Курсор непрозрачный — не разбирайте и не изменяйте его.

Допустимые значения фильтров берите из GET /cars/facets: поле value каждого варианта передается в одноименный параметрGET /cars, а label показывается пользователю. Текстовый поиск — параметр q.

Обход каталога курсором

let cursor = null;

do {
  const url = new URL("https://carhubauto.ru/api/v2/cars");
  url.searchParams.set("limit", "50");
  if (cursor) url.searchParams.set("cursor", cursor);

  const page = await (await fetch(url)).json();
  render(page.data);

  cursor = page.pagination.next_cursor;
} while (cursor);

Фасеты и фильтры

# 1. Значения и диапазоны для фильтров
curl 'https://carhubauto.ru/api/v2/cars/facets'

# 2. Каталог с выбранными фильтрами
curl 'https://carhubauto.ru/api/v2/cars?manufacturer=Kia\
&model=Carnival&year_min=2021&source_country=KR'

Марки и модели

Справочник GET /catalog/brands содержит марки с логотипами, числом моделей и сводной статистикой базы.

GET /catalog/brands/{slug}/models — модели марки с годами выпуска, числом поколений и фото для превью. Слаги из справочника используются в постоянных ссылках CarHub.

Справочник марок

# Марки с логотипами и статистикой
curl 'https://carhubauto.ru/api/v2/catalog/brands?q=bmw'

# Модели марки по slug из предыдущего ответа
curl 'https://carhubauto.ru/api/v2/catalog/brands/bmw/models'

Справочник

Endpoints, параметры и схемы

Полное описание каждого endpoint: параметры, схемы ответов и примеры. Справочник генерируется из OpenAPI-спецификации — той же, по которой работает API, поэтому он всегда соответствует продакшену.

Ошибки и лимиты

Формат ошибок

Ошибки возвращаются в JSON. Поле detail содержит строку с причиной, а при ошибке валидации (422) — список проблемных параметров с указанием, какой именно параметр и почему не принят.

Публичный лимит — 30 запросов в секунду с одного IP. Кешируйте ответы на своей стороне: карточки и фасеты обновляются не чаще, чем раз в несколько минут.

Примеры тела ошибки

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

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

Код	Когда возвращается	Что делать
`400`	Невалидная комбинация параметров, например `price_min` больше `price_max`.	Исправьте параметры запроса.
`404`	Объект не найден: автомобиль снят с публикации или указан несуществующий слаг.	Уберите объект из выдачи. Карточки могут исчезать — это нормально для живого каталога.
`422`	Параметр не прошел валидацию: неверный тип или значение вне диапазона.	Сверьте параметры со справочником.
`429`	Превышен лимит: более 30 запросов в секунду с одного IP.	Повторите запрос с задержкой, кешируйте ответы на своей стороне.
`5xx`	Временная ошибка на стороне CarHub.	Повторите запрос через несколько секунд.