01 Руководства

Документация API: первый запрос за пять минут

apiauto.space — REST API с JSON: каталоги подержанных машин Кореи (Encar), Китая (Che168) и аукционов США (Copart, IAAI) в одном формате записи.

Корея (Encar) — более 140 000 активных машин; Китай (Che168) — более 230 000; США (Copart и IAAI) — более 80 000. Чем рынки отличаются — в границах данных.

Базовый адрес и схема

ЧтоЗначение
Базовый адресhttps://api.apiauto.space/v1
ФорматJSON, UTF-8; время — ISO 8601 UTC
КлючX-API-Key — ключ и заголовки
Пагинациякурсором: next_cursor из прошлой страницы
Схемаopenapi.json · Swagger UI · Redoc

Цикл интеграции

  1. ИмпортВыгрузите рынок к себе: GET /v1/cars с курсором, до 100 машин за запрос.
  2. Опрос измененийРаз в час спрашивайте GET /v1/changes?since=…: новые машины, снятые и изменения цен.
  3. ОбновлениеНовые — по GET /v1/cars/{id}, снятые помечайте проданными. Подробно — в синхронизации каталога.

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

  1. Откройте бота и возьмите демо-ключ: сутки, 100 запросов за данными, до 20 машин за запрос, все три рынка.
  2. Сохраните ключ в переменную окружения APIAUTO_KEY: он показывается один раз.
  3. Отправьте запрос:
curl
curl -s "https://api.apiauto.space/v1/cars?market=kr&brand=Kia&limit=20" \
  -H "X-API-Key: $APIAUTO_KEY"

Есть готовые клиенты: pip install apiauto-space — библиотека для Python, npm i apiauto — библиотека для JavaScript и TypeScript. Их код и примеры для Encar — на GitHub.

Ответ — страница машин и курсор следующей страницы. Так выглядит одна запись (сокращено: две ссылки на фото и первые поля raw):

GET /v1/cars/encar:43123480
{
  "id": "encar:43123480",
  "market": "kr",
  "source": "encar",
  "source_id": "43123480",
  "title": "2024 Volvo V60 Cross Country 2 Gen B5 Ultimate AWD",
  "brand": "Volvo",
  "model": "V60 Cross Country",
  "generation": "V60 Cross Country 2 Gen",
  "trim": "B5 Ultimate AWD",
  "year": 2024,
  "mileage_km": 33375,
  "fuel": "gasoline",
  "transmission": null,
  "engine_cc": null,
  "body_type": null,
  "color": null,
  "vin": null,
  "price": {
    "amount": "40900000.00",
    "currency": "KRW"
  },
  "price_usd": "30101.68",
  "location": {
    "country": "KR",
    "region": "Daegu",
    "city": null
  },
  "photo_count": 4,
  "listing_url": "https://fem.encar.com/cars/detail/43123480",
  "is_active": true,
  "first_seen_at": "2026-11-09T10:07:40.261677Z",
  "last_seen_at": "2026-11-09T10:07:40.261677Z",
  "disappeared_at": null,
  "updated_at": "2026-11-09T10:07:40.261677Z",
  "source_mode": "replica",
  "photos": [
    "https://api.apiauto.space/img/encar:43123480/1.jpg?exp=…&sig=…",
    "https://api.apiauto.space/img/encar:43123480/2.jpg?exp=…&sig=…"
  ],
  "raw": {
    "badge": "B5 얼티메이트 AWD",
    "has_vin": false,
    "form_year": "202405",
    "sell_type": "normal",
    "body_class": null,
    "office_city": "대구",
    "badge_detail": null,
    "has_accident": false
  }
}

Держите ключ на сервере. API не разрешает запросы из браузера (CORS выключен), а ключ в коде страницы увидит любой посетитель.

Руководства

Ключ и заголовкиКак передавать ключ API в заголовке X-API-Key, где его хранить, как перевыпустить и что значат заголовки квоты и лимитов в ответе.
Синхронизация каталогаКак выгрузить каталог Encar, Che168 или Copart и IAAI к себе курсором и держать его свежим по ленте изменений: новые, снятые машины и цены.
Запись о машине и фотоПоля записи о машине, одинаковые для Encar, Che168, Copart и IAAI: марка, модель, цена, пробег, место, фото и raw; как устроены подписанные ссылки на фото.
Квота и лимитыЧто списывает квоту — машины и события, а не запросы; лимиты четырёх тарифов, обновление квоты и работа ключа после окончания оплаты.
ОшибкиТело ответа с ошибкой и коды HTTP от 400 до 503 с полем error: что значит каждый, что делать при 402, 429 и 503 и когда повторять запрос.
Границы данныхЧем отличаются данные Кореи, Китая и США в API: объём, обновление, VIN, фото, чего нет у каждого источника и как узнать возраст копии рынка.
Версии и changelogПравила совместимости внутри /v1: поля только добавляются, несовместимые изменения выйдут в /v2. Что менялось в API по месяцам, с датами.

Методы

GET /v1/cars Каталог машинМетод GET /v1/cars: фильтры по марке, модели, году, цене и пробегу, сортировка, курсор и примеры ответа на настоящих машинах Encar, Che168, Copart и IAAI.
GET /v1/cars/{id} Машина по idМетод GET /v1/cars/{id}: полная запись одной машины Encar, Che168, Copart или IAAI по id вида encar:…, включая снятые с продажи за 14 дней.
GET /v1/changes Лента измененийМетод GET /v1/changes: новые машины, снятые с продажи, снижение и рост цены с порогом в процентах — с момента since, с курсором. Тарифы Pro, Max и демо.
GET /v1/us/live Живой поиск СШАМетод GET /v1/us/live: поиск лотов Copart и IAAI у поставщика данных аукционов, когда машины нет в копии. Тарифы Pro и Max, отдельный счётчик.
GET /v1/references/… СправочникиБесплатные справочники: марки и модели рынка с числом машин, допустимые значения топлива, коробки и кузова, свежесть рынков. Квоту не тратят.
GET /v1/usage Расход квотыМетод GET /v1/usage: тариф, срок, квота периода и сколько из неё потрачено — всего и по рынкам, включая живой поиск США. Бесплатно.
ЕщёЧто делаетКвота
GET /img/{id}/{n}.jpgФото машины по подписанной ссылке из записи.бесплатно
GET /healthzПроверка состояния: 503, если какой-то рынок старше порога свежести.бесплатно