Документация к REST API v2

Купленный ключ подходит к любой версии API

Общая информация

• Базовый URL: https://api.cars-base.ru
• Текущая версия: v2
• Ответы: JSON
• Аутентификация: по токену через ?token=...
• Демо режим: ?token=test

Схема базы

https://app.diagrams.net/#G1gtb33PWXD6WnKII0CBNT6_wpDOTJvRae

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

Формат

• Все запросы (кроме /, /status, /me, /download, /health, /dic) требуют параметр ?token=ваш_токен
• Для тестирования можно использовать ?token=test, включающий демо-режим с ограничением 50 первых марок

Проверка токена

GET /me?token=ваш_токен

Ответ:

{
  "data": {
    "token": "...",
    "email": "user@example.com",
    "created_at": "2024-10-01T00:00:00.000Z",
    "expiration": 12,
    "expires_at": "2025-10-01T00:00:00.000Z",
    "is_expired": false
  },
  "meta": { "duration_ms": 1.23 }
}

Общие параметры запроса

Структура эндпоинтов

Все основные ресурсы доступны по маршрутам:

GET /full
GET /marks
GET /models
GET /generations
GET /configurations
GET /modifications
GET /specifications
GET /specifications_raw
GET /options

Пример запроса:

GET /models?token=xxx&pageSize=50&sort_by=name&fields=id,name,mark_id

Живые примеры:
https://api.cars-base.ru/marks?token=test
https://api.cars-base.ru/models?mark_id=BMW&token=test
https://api.cars-base.ru/generations?model_id=BMW_1ER&token=test

Все марки и модели: https://api.cars-base.ru/full

Ответ:

{
  "data": [...],
  "meta": {
    "total": 1234,
    "count": 50,
    "pageSize": 50,
    "after_id": null,
    "next_after_id": 102,
    "demoMode": false,
    "duration_ms": 5.12
  }
}

Детали модификации

GET /modifications/:id/details?token=xxx

Ответ:

{
  "data": {
    "id": 123,
    "name": "1.6 MT",
    "specifications": {"engine_power": "123 hp", ...},
    "options": {"airbags": 2, ...}
  },
  "meta": {"count": 1, "duration_ms": 2.01}
}

Скачивание файлов

Список файлов

GET /download

Ответ:

{
  "files": [
    {
      "filename": "carsbase2_dump.sql",
      "size": 103894726,
      "updated_at": "2025-07-28T23:47:05.706Z",
      "description": "База в формате SQL с таблицами marks, models, generations, configurations, modifications, specifications, options и связями между ними."
    }
  ],
  "count": 1
}

Скачать файл

GET /download/:filename?token=xxx

• В демо-режиме можно скачать файлы содержащие первые 50 марок
• Ответ — потоковое скачивание

Описание всех файлов: https://api.cars-base.ru/download

• База в формате SQL с таблицами marks, models, generations, configurations, modifications, specifications, options и связями между ними:
  • https://api.cars-base.ru/download/carsbase2_dump.sql?token=test
• База в формате CSV с таблицами marks, models, generations, configurations, modifications, specifications, options и связями между ними:
  • https://api.cars-base.ru/download/csv_exports.zip?token=test
• CSV формат базы. Все модификации в одной таблице. Названия колонок технические (id):
  • https://api.cars-base.ru/download/catalog_full.csv?token=test
• CSV формат базы. Все модификации в одной таблице. Названия колонок русскоязычные:
  • https://api.cars-base.ru/download/catalog_full_rus.csv?token=test
• JSON формат базы. Вложенный формат:
  • https://api.cars-base.ru/download/catalog_full.json?token=test
• Excel формат базы. Все модификации в одной таблице. Названия колонок русскоязычные:
  • https://api.cars-base.ru/download/catalog_full.xlsx?token=test
• Логотипы марок. Имя файла соответствует mark_id.png:
  • https://api.cars-base.ru/download/logos.zip?token=test
• Фотографии конфигураций (кузовов). Одна конфигурация одно фото имя файла соответствует configuration_id_main.jpg:
  • https://api.cars-base.ru/download/photos_main.zip?token=test
• Также есть все фотографии каждой конфигурации пишите в телеграм https://t.me/gulpsun9

Статус сервера

GET /status

Ответ:

{
  "last_update": "2025-07-29T12:00:00Z",
  "counts": {
    "marks": 20,
    "models": 450,
    "generations": 123,
    "configurations": 789,
    "modifications": 9999
  },
  "meta": {"duration_ms": 1.55}
}

Коды ошибок

Пагинация

• Можно использовать page и pageSize. Пример: ?page=10&pageSize=25
• При больших данных предпочтительна keyset пагинация через after_id. Пример: ?after_id=102

Справочники

https://api.cars-base.ru/dic

Получить все справочники

GET /dic

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

GET /dic/:id

Пример: /dic/body_type

Общее

https://api.cars-base.ru/dic/general

Типы кузовов

https://api.cars-base.ru/dic/body_types

Спецификации

https://api.cars-base.ru/dic/specifications

Спецификации RAW словарь

https://api.cars-base.ru/dic/specifications_raw

Опции

https://api.cars-base.ru/dic/options