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 |
Цикл интеграции
- ИмпортВыгрузите рынок к себе:
GET /v1/carsс курсором, до 100 машин за запрос. - Опрос измененийРаз в час спрашивайте
GET /v1/changes?since=…: новые машины, снятые и изменения цен. - ОбновлениеНовые — по
GET /v1/cars/{id}, снятые помечайте проданными. Подробно — в синхронизации каталога.
Быстрый старт
- Откройте бота и возьмите демо-ключ: сутки, 100 запросов за данными, до 20 машин за запрос, все три рынка.
- Сохраните ключ в переменную окружения APIAUTO_KEY: он показывается один раз.
- Отправьте запрос:
curl -s "https://api.apiauto.space/v1/cars?market=kr&brand=Kia&limit=20" \
-H "X-API-Key: $APIAUTO_KEY"import os
import httpx
client = httpx.Client(
base_url="https://api.apiauto.space/v1",
headers={"X-API-Key": os.environ["APIAUTO_KEY"]},
timeout=30,
)
# Two pages of 20: every car returned counts against the quota.
params = {"market": "kr", "brand": "Kia", "limit": 20}
for _ in range(2):
page = client.get("/cars", params=params).raise_for_status().json()
for car in page["items"]:
print(car["id"], car["title"], car["price"])
if not page["next_cursor"]:
break
params["cursor"] = page["next_cursor"]const response = await fetch(
"https://api.apiauto.space/v1/cars?market=cn&limit=20",
{ headers: { "X-API-Key": process.env.APIAUTO_KEY } },
);
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { items, next_cursor } = await response.json();
console.log(items.map((car) => car.title));
console.log("records left:", response.headers.get("X-Quota-Remaining"));<?php
$ch = curl_init("https://api.apiauto.space/v1/cars?market=us&limit=20");
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("APIAUTO_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("HTTP $status: $body");
}
foreach (json_decode($body, true)["items"] as $car) {
echo $car["id"], " ", $car["title"], PHP_EOL;
}Есть готовые клиенты: pip install apiauto-space — библиотека для Python, npm i apiauto — библиотека для JavaScript и TypeScript. Их код и примеры для Encar — на GitHub.
Ответ — страница машин и курсор следующей страницы. Так выглядит одна запись (сокращено: две ссылки на фото и первые поля raw):
{
"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, если какой-то рынок старше порога свежести. | бесплатно |