**01** Руководства # Документация API: первый запрос за пять минут apiauto.space — REST API с JSON: каталоги подержанных машин Кореи (Encar), Китая (Che168) и аукционов США (Copart, IAAI) в одном формате записи. Корея (Encar) — более 140 000 активных машин; Китай (Che168) — более 230 000; США (Copart и IAAI) — более 80 000. Чем рынки отличаются — в [границах данных](https://apiauto.space/docs/markets/). ## Базовый адрес и схема | Что | Значение | | --- | --- | | Базовый адрес | `https://api.apiauto.space/v1` | | Формат | JSON, UTF-8; время — ISO 8601 UTC | | Ключ | `X-API-Key` — [ключ и заголовки](https://apiauto.space/docs/auth/) | | Пагинация | курсором: next_cursor из прошлой страницы | | Схема | [openapi.json](https://api.apiauto.space/openapi.json) · [Swagger UI](https://api.apiauto.space/docs/swagger) · [Redoc](https://api.apiauto.space/docs/redoc) | ## Цикл интеграции 1. **Импорт** Выгрузите рынок к себе: `GET /v1/cars` с курсором, до 100 машин за запрос. 2. **Опрос изменений** Раз в час спрашивайте `GET /v1/changes?since=…`: новые машины, снятые и изменения цен. 3. **Обновление** Новые — по `GET /v1/cars/{id}`, снятые помечайте проданными. Подробно — в [синхронизации каталога](https://apiauto.space/docs/sync/). ## Быстрый старт 1. Откройте [бота](https://t.me/apiautospace_bot?start=demo) и возьмите демо-ключ: сутки, 100 запросов за данными, до 20 машин за запрос, все три рынка. 2. Сохраните ключ в переменную окружения APIAUTO_KEY: он показывается один раз. 3. Отправьте запрос: curl: ```bash curl -s "https://api.apiauto.space/v1/cars?market=kr&brand=Kia&limit=20" \ -H "X-API-Key: $APIAUTO_KEY" ``` Python · httpx: ```python 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"] ``` JavaScript · fetch: ```js 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: ```php ["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](https://pypi.org/project/apiauto-space/), `npm i apiauto` — [библиотека для JavaScript и TypeScript](https://www.npmjs.com/package/apiauto). Их код и примеры для Encar — [на GitHub](https://github.com/apiauto-space). Ответ — страница машин и курсор следующей страницы. Так выглядит одна запись (сокращено: две ссылки на фото и первые поля raw): GET /v1/cars/encar:43123480: ```json { "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 выключен), а ключ в коде страницы увидит любой посетитель. ## Руководства [**Ключ и заголовки**](https://apiauto.space/docs/auth/)Как передавать ключ API в заголовке X-API-Key, где его хранить, как перевыпустить и что значат заголовки квоты и лимитов в ответе. [**Синхронизация каталога**](https://apiauto.space/docs/sync/)Как выгрузить каталог Encar, Che168 или Copart и IAAI к себе курсором и держать его свежим по ленте изменений: новые, снятые машины и цены. [**Запись о машине и фото**](https://apiauto.space/docs/record/)Поля записи о машине, одинаковые для Encar, Che168, Copart и IAAI: марка, модель, цена, пробег, место, фото и raw; как устроены подписанные ссылки на фото. [**Квота и лимиты**](https://apiauto.space/docs/limits/)Что списывает квоту — машины и события, а не запросы; лимиты четырёх тарифов, обновление квоты и работа ключа после окончания оплаты. [**Ошибки**](https://apiauto.space/docs/errors/)Тело ответа с ошибкой и коды HTTP от 400 до 503 с полем error: что значит каждый, что делать при 402, 429 и 503 и когда повторять запрос. [**Границы данных**](https://apiauto.space/docs/markets/)Чем отличаются данные Кореи, Китая и США в API: объём, обновление, VIN, фото, чего нет у каждого источника и как узнать возраст копии рынка. [**Версии и changelog**](https://apiauto.space/docs/changelog/)Правила совместимости внутри /v1: поля только добавляются, несовместимые изменения выйдут в /v2. Что менялось в API по месяцам, с датами. ## Методы [`GET /v1/cars` **Каталог машин**](https://apiauto.space/docs/endpoints/cars/)Метод GET /v1/cars: фильтры по марке, модели, году, цене и пробегу, сортировка, курсор и примеры ответа на настоящих машинах Encar, Che168, Copart и IAAI. [`GET /v1/cars/{id}` **Машина по id**](https://apiauto.space/docs/endpoints/car/)Метод GET /v1/cars/{id}: полная запись одной машины Encar, Che168, Copart или IAAI по id вида encar:…, включая снятые с продажи за 14 дней. [`GET /v1/changes` **Лента изменений**](https://apiauto.space/docs/endpoints/changes/)Метод GET /v1/changes: новые машины, снятые с продажи, снижение и рост цены с порогом в процентах — с момента since, с курсором. Тарифы Pro, Max и демо. [`GET /v1/us/live` **Живой поиск США**](https://apiauto.space/docs/endpoints/live/)Метод GET /v1/us/live: поиск лотов Copart и IAAI у поставщика данных аукционов, когда машины нет в копии. Тарифы Pro и Max, отдельный счётчик. [`GET /v1/references/…` **Справочники**](https://apiauto.space/docs/endpoints/references/)Бесплатные справочники: марки и модели рынка с числом машин, допустимые значения топлива, коробки и кузова, свежесть рынков. Квоту не тратят. [`GET /v1/usage` **Расход квоты**](https://apiauto.space/docs/endpoints/usage/)Метод GET /v1/usage: тариф, срок, квота периода и сколько из неё потрачено — всего и по рынкам, включая живой поиск США. Бесплатно. | Ещё | Что делает | Квота | | --- | --- | --- | | `GET /img/{id}/{n}.jpg` | Фото машины по подписанной ссылке из записи. | бесплатно | | `GET /healthz` | Проверка состояния: 503, если какой-то рынок старше порога свежести. | бесплатно | --- Страница: https://apiauto.space/docs/