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

Cars Base API отдает каталог автомобилей, справочники, технические характеристики, опции, файловые выгрузки, логотипы и фотографии. Эта страница описывает маршруты из текущего API-сервера, параметры запроса, варианты ответов и типовые сценарии интеграции.

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

Base URL: https://api.cars-base.ru
Формат ответов: JSON, кроме скачивания файлов.
Авторизация: большинство данных запрашивается с ?token=....
Демо-токен: token=test.
Лимит запросов: 1000 запросов в минуту на токен или IP. Скачивание файлов не ограничивается этим лимитом.
Максимальный pageSize: 1000.

GET https://api.cars-base.ru/marks?token=test&pageSize=10&sort_by=id

{
  "data": [
    {
      "id": "ABARTH",
      "name": "Abarth",
      "cyrillic_name": "Абарт",
      "country": "Италия"
    }
  ],
  "meta": {
    "total": 1,
    "count": 1,
    "pageSize": 10,
    "page": 1,
    "after_id": null,
    "next_after_id": "ABARTH",
    "demoMode": true,
    "duration_ms": 3.12
  }
}

Схема базы

Открыть схему базы

Основные связи:

Уровень	Таблица	Родительский ключ
Марка	`marks`	-
Модель	`models`	`mark_id`
Поколение	`generations`	`model_id`, `mark_id`
Конфигурация кузова	`configurations`	`generation_id`, `model_id`, `mark_id`
Модификация	`modifications`	`configuration_id`, `generation_id`, `model_id`, `mark_id`
Характеристики	`specifications`, `specifications_raw`	`id` модификации
Опции	`options`	`id` модификации

Авторизация

Где нужен токен

Токен нужен для маршрутов данных и скачивания конкретного файла:

GET /marks?token=ваш_ключ
GET /models?mark_id=BMW&token=ваш_ключ
GET /download/catalog_full.json?token=ваш_ключ

Без токена доступны:

GET /
GET /status
GET /download
GET /dic
GET /dic/:id
GET /full
GET /favicon.ico

Демо-режим

token=test включает демо-базу для табличных маршрутов. Он подходит для проверки структуры ответа, фильтров, пагинации и скачивания демо-файлов.

GET /models?mark_id=BMW&token=test

Ошибки авторизации

{
  "error": "Unauthorized",
  "message": "Не найден параметр ?token=... или используйте ?token=test"
}

{
  "error": "TokenExpired",
  "message": "Токен истек 01.01.2026, 12:00:00. Купите тариф"
}

Общие параметры табличных маршрутов

Эти параметры работают для:

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

Параметр	Тип	Значение по умолчанию	Описание
`token`	string	-	Ключ доступа или `test`.
`page`	number	`1`	Offset-пагинация. Игнорируется, если передан `after_id`.
`pageSize`	number	`50`	Размер страницы. Максимум `1000`.
`after_id`	string \| number	-	Keyset-пагинация: вернет строки с `id > after_id`, отсортированные по `id ASC`.
`sort_by`	string	-	Поле сортировки. Имя поля должно содержать только буквы, цифры и `_`.
`sort_dir`	`ASC` \| `DESC`	`ASC`	Направление сортировки. Любое значение кроме `DESC` трактуется как `ASC`.
`fields`	string	`*`	Список полей через запятую. Невалидные имена игнорируются.
`updated_after`	ISO date/string	-	Фильтр `updated_at > YYYY-MM-DD`.
любое поле таблицы	string \| number	-	Фильтр точного совпадения: `mark_id=BMW`, `model_id=BMW_3ER`, `body_type=sedan`.

Ограничения:

имя поля, таблицы и сортировки: только a-z, A-Z, 0-9, _;
максимальная длина имени поля: 32 символа;
максимальная длина строкового параметра: 2000 символов;
максимум 64 фильтра в одном запросе;
максимум 128 полей в fields.

Формат ответа табличных маршрутов

{
  "data": [],
  "meta": {
    "total": 0,
    "count": 0,
    "pageSize": 50,
    "page": 1,
    "after_id": null,
    "next_after_id": null,
    "demoMode": false,
    "duration_ms": 1.25
  }
}

Поле	Описание
`data`	Массив строк таблицы. `null` значения не возвращаются. В `options` также скрываются значения `0`.
`meta.total`	Общее количество строк для offset-пагинации. При `after_id` равно `null`.
`meta.count`	Количество строк в текущем ответе.
`meta.pageSize`	Фактический размер страницы после ограничения максимумом.
`meta.page`	Текущая страница для offset-пагинации. При `after_id` не используется.
`meta.after_id`	Переданный курсор.
`meta.next_after_id`	`id` последней строки ответа. Используйте как следующий `after_id`.
`meta.demoMode`	`true`, если используется `token=test`.
`meta.duration_ms`	Время обработки на сервере.

Пагинация

Offset-пагинация

Подходит для интерфейсов, где нужна конкретная страница.

GET /modifications?token=xxx&page=2&pageSize=100&sort_by=id

Keyset-пагинация

Подходит для синхронизации больших таблиц. Берите meta.next_after_id из ответа и передавайте его в следующий запрос.

GET /modifications?token=xxx&pageSize=1000&after_id=2467479_8424325_2467502

При after_id сервер всегда сортирует по id ASC, а meta.total не считается.

Поля, фильтры и сортировка

Выбрать только нужные поля

GET /models?token=xxx&mark_id=BMW&fields=id,name,cyrillic_name,year_from

Отсортировать

GET /marks?token=xxx&sort_by=name&sort_dir=ASC

Получить изменения после даты

GET /modifications?token=xxx&updated_after=2026-07-01&pageSize=1000

Маршруты каталога

GET /marks

Возвращает марки автомобилей.

Авторизация: token обязателен, token=test разрешен.

Частые поля ответа:

Поле	Описание
`id`	Технический идентификатор марки, например `BMW`.
`name`	Название латиницей.
`cyrillic_name`	Название кириллицей.
`numeric_id`	Числовой идентификатор источника.
`year_from`, `year_to`	Годы выпуска марки в каталоге.
`popular`	Признак популярной марки.
`country`	Страна.
`updated_at`	Дата обновления строки.

Пример:

GET /marks?token=test&pageSize=20&fields=id,name,cyrillic_name,country&sort_by=name

{
  "data": [
    {
      "id": "BMW",
      "name": "BMW",
      "cyrillic_name": "БМВ",
      "country": "Германия"
    }
  ],
  "meta": {
    "total": 50,
    "count": 20,
    "pageSize": 20,
    "page": 1,
    "after_id": null,
    "next_after_id": "BMW",
    "demoMode": true,
    "duration_ms": 2.4
  }
}

GET /models

Возвращает модели. Обычно фильтруется по mark_id.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`mark_id`	Идентификатор марки из `/marks`.
`fields`	Например `id,name,cyrillic_name,year_from,year_to`.

Частые поля ответа:

Поле	Описание
`id`	Идентификатор модели.
`mark_id`	Родительская марка.
`name`, `cyrillic_name`	Названия.
`year_from`, `year_to`	Годы выпуска.
`class`	Класс автомобиля.
`updated_at`	Дата обновления строки.

Пример:

GET /models?token=test&mark_id=BMW&pageSize=50&sort_by=year_from&sort_dir=DESC

{
  "data": [
    {
      "id": "BMW_3ER",
      "mark_id": "BMW",
      "name": "3 серии",
      "year_from": 1975
    }
  ],
  "meta": {
    "total": 18,
    "count": 18,
    "pageSize": 50,
    "page": 1,
    "next_after_id": "BMW_3ER",
    "demoMode": true,
    "duration_ms": 3.7
  }
}

GET /generations

Возвращает поколения моделей. Обычно фильтруется по model_id.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`model_id`	Идентификатор модели из `/models`.
`mark_id`	Можно использовать для дополнительного ограничения.

Частые поля ответа:

Поле	Описание
`id`	Идентификатор поколения.
`model_id`, `mark_id`	Родительская модель и марка.
`name`	Название поколения.
`year_from`, `year_to`	Годы выпуска поколения.
`updated_at`	Дата обновления строки.

Пример:

GET /generations?token=test&model_id=BMW_3ER&fields=id,name,year_from,year_to

{
  "data": [
    {
      "id": "BMW_3ER_G20",
      "name": "G20/G21",
      "year_from": 2018,
      "year_to": null
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 50,
    "page": 1,
    "demoMode": true,
    "duration_ms": 2.9
  }
}

GET /configurations

Возвращает конфигурации кузова внутри поколения.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`generation_id`	Идентификатор поколения из `/generations`.
`model_id`, `mark_id`	Дополнительные фильтры.
`body_type`	Тип кузова, например `sedan`, `hatchback`, `suv`.

Частые поля ответа:

Поле	Описание
`id`	Идентификатор конфигурации.
`generation_id`, `model_id`, `mark_id`	Родительские идентификаторы.
`name`	Название конфигурации, если есть.
`body_type`	Тип кузова.
`doors_count`	Количество дверей.
`updated_at`	Дата обновления строки.

Пример:

GET /configurations?token=test&generation_id=BMW_3ER_G20&fields=id,body_type,doors_count

{
  "data": [
    {
      "id": "BMW_3ER_G20_SEDAN",
      "body_type": "sedan",
      "doors_count": 4
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 50,
    "page": 1,
    "demoMode": true,
    "duration_ms": 2.6
  }
}

GET /modifications

Возвращает модификации, комплектации и агрегатные версии. Обычно фильтруется по configuration_id.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`configuration_id`	Идентификатор конфигурации из `/configurations`.
`generation_id`, `model_id`, `mark_id`	Дополнительные фильтры.
`is_closed`	Фильтр закрытых/актуальных модификаций, если поле есть в данных.

Частые поля ответа:

Поле	Описание
`id`	Идентификатор модификации. Он также используется в `specifications`, `specifications_raw` и `options`.
`configuration_id`, `generation_id`, `model_id`, `mark_id`	Родительские идентификаторы.
`name`	Название модификации.
`group_name`	Группа комплектации/версии.
`offers_price_from`, `offers_price_to`	Диапазон цены предложений, если есть.
`is_closed`	Признак закрытой/архивной записи.
`updated_at`	Дата обновления строки.

Пример:

GET /modifications?token=test&configuration_id=BMW_3ER_G20_SEDAN&pageSize=20

{
  "data": [
    {
      "id": "BMW_3ER_G20_SEDAN_320I",
      "configuration_id": "BMW_3ER_G20_SEDAN",
      "name": "320i",
      "group_name": "Base"
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 20,
    "page": 1,
    "next_after_id": "BMW_3ER_G20_SEDAN_320I",
    "demoMode": true,
    "duration_ms": 3.1
  }
}

GET /specifications

Возвращает нормализованные технические характеристики модификаций. id совпадает с modifications.id.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`id`	Идентификатор модификации.
`fields`	Список нужных характеристик, например `id,horse_power,transmission,drive,volume`.

Ответ: табличный envelope { data, meta }. В строках не возвращаются null значения.

Пример:

GET /specifications?token=test&id=BMW_3ER_G20_SEDAN_320I&fields=id,horse_power,transmission,drive,volume

{
  "data": [
    {
      "id": "BMW_3ER_G20_SEDAN_320I",
      "horse_power": 184,
      "transmission": "автоматическая",
      "drive": "задний",
      "volume": 1998
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 50,
    "page": 1,
    "demoMode": true,
    "duration_ms": 2.2
  }
}

GET /specifications_raw

Возвращает исходные/raw-характеристики. Используйте, если нужны значения ближе к первоисточнику или расширенная сверка с specifications.

Авторизация: token обязателен, token=test разрешен.

Частые параметры: такие же, как у /specifications.

Пример:

GET /specifications_raw?token=test&id=BMW_3ER_G20_SEDAN_320I&pageSize=1

{
  "data": [
    {
      "id": "BMW_3ER_G20_SEDAN_320I",
      "horse_power": "184",
      "transmission": "AT"
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 1,
    "page": 1,
    "demoMode": true,
    "duration_ms": 2.5
  }
}

GET /options

Возвращает опции модификаций. id совпадает с modifications.id. В ответе скрываются null и 0, поэтому оставшиеся поля обычно означают наличие опции.

Авторизация: token обязателен, token=test разрешен.

Частые параметры:

Параметр	Описание
`id`	Идентификатор модификации.
`fields`	Например `id,abs,airbag_driver,apple_carplay,climate_control_2`.

Пример:

GET /options?token=test&id=BMW_3ER_G20_SEDAN_320I&fields=id,abs,airbag_driver,apple_carplay

{
  "data": [
    {
      "id": "BMW_3ER_G20_SEDAN_320I",
      "abs": 1,
      "airbag_driver": 1,
      "apple_carplay": 1
    }
  ],
  "meta": {
    "count": 1,
    "pageSize": 50,
    "page": 1,
    "demoMode": true,
    "duration_ms": 2.1
  }
}

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

GET /modifications/:id/details

Возвращает одну модификацию вместе с характеристиками, raw-характеристиками и опциями.

Авторизация: token обязателен. token=test проходит авторизацию как демо-токен.

Path-параметры:

Параметр	Описание
`id`	Идентификатор модификации из `/modifications`.

Пример:

GET /modifications/BMW_3ER_G20_SEDAN_320I/details?token=test

Ответ, если модификация найдена:

{
  "data": {
    "id": "BMW_3ER_G20_SEDAN_320I",
    "name": "320i",
    "configuration_id": "BMW_3ER_G20_SEDAN",
    "specifications": {
      "horse_power": 184,
      "transmission": "автоматическая"
    },
    "specifications_raw": {
      "horse_power": "184"
    },
    "options": {
      "abs": 1,
      "airbag_driver": 1
    }
  },
  "meta": {
    "count": 1,
    "duration_ms": 3.9
  }
}

Ответ, если модификация не найдена:

{
  "data": null,
  "meta": {
    "count": 0,
    "duration_ms": 1.1
  }
}

Справочники

GET /dic

Возвращает все таблицы-справочники с суффиксом _dic.

Авторизация: не нужна.

Пример:

GET /dic

{
  "data": {
    "general_dic": [
      {
        "id": "mark-id",
        "name": "Марка"
      }
    ],
    "body_types_dic": [
      {
        "body_type": "sedan",
        "name": "седан"
      }
    ],
    "specifications_dic": [],
    "options_dic": []
  },
  "errors": null,
  "meta": {
    "tables": 4,
    "duration_ms": 8.4
  }
}

GET /dic/:id

Возвращает один справочник из таблицы ${id}_dic.

Авторизация: не нужна.

Path-параметры:

Параметр	Описание
`id`	Имя справочника без `_dic`: `general`, `body_types`, `specifications`, `specifications_raw`, `options`.

Важно: ответ этого маршрута — массив строк напрямую, без обертки { data, meta }.

Примеры:

GET /dic/options
GET /dic/specifications
GET /dic/body_types

[
  {
    "category_name": "Безопасность",
    "group_code": "airbags",
    "group_name": "Подушки безопасности",
    "option_code": "airbag_driver",
    "option_name": "водителя",
    "option_full_name": "Подушка безопасности водителя"
  }
]

Агрегированный список марок и моделей

GET /full

Возвращает все марки и вложенные модели.

Авторизация: не нужна.

Пример:

GET /full

{
  "data": [
    {
      "id": "BMW",
      "name": "BMW",
      "models": [
        {
          "id": "BMW_3ER",
          "mark_id": "BMW",
          "name": "3 серии"
        }
      ]
    }
  ],
  "meta": {
    "duration_ms": 12.8
  }
}

Статус API

GET /status

Возвращает дату последнего обновления и счетчики основных таблиц.

Авторизация: не нужна.

Пример:

GET /status

{
  "last_update": "2026-07-09T10:12:30.000Z",
  "counts": {
    "marks": 100,
    "models": 4000,
    "generations": 9000,
    "configurations": 12000,
    "modifications": 80000
  },
  "meta": {
    "duration_ms": 1.55
  }
}

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

GET /me

Проверяет токен и возвращает срок действия.

Авторизация: передается через query-параметр token.

Варианты:

Вариант	Ответ
`token=test`	Демо-ответ без срока действия.
действующий ключ	Email, дата создания, срок, дата окончания, флаг `is_expired`.
неизвестный ключ	Объект `{ "error": "Unauthorized", "message": "Ключ не найден" }`.

Примеры:

GET /me?token=test

{
  "data": {
    "token": "test",
    "demoMode": true,
    "message": "Демо токен активен. Доступ к данным ограничен."
  },
  "meta": {
    "duration_ms": 0.2
  }
}

GET /me?token=ваш_ключ

{
  "data": {
    "token": "ваш_ключ",
    "email": "client@example.com",
    "created_at": "2026-01-10 12:00:00",
    "expiration": 12,
    "expires_at": "2027-01-10T12:00:00.000Z",
    "is_expired": false
  },
  "meta": {
    "duration_ms": 1.3
  }
}

Файловые выгрузки

GET /download

Возвращает список доступных файлов выгрузки.

Авторизация: не нужна.

Особенности: файлы с префиксом demo_ скрыты из списка. Для каждого файла подтягивается описание из download.json, если оно есть.

Пример:

GET /download

{
  "files": [
    {
      "filename": "catalog_full.json",
      "size": 123456789,
      "updated_at": "2026-07-09T10:00:00.000Z",
      "description": "JSON формат базы. Вложенный формат."
    }
  ],
  "count": 1
}

GET /download/:filename

Скачивает файл выгрузки.

Авторизация: token обязателен, token=test разрешен.

Path-параметры:

Параметр	Описание
`filename`	Имя файла из `/download`. Разрешены только буквы, цифры, `.`, `_`, `-`; максимум 128 символов.

Варианты доступа:

Вариант	Поведение
`token=test`	Сервер ищет файл `demo_${filename}`.
обычный ключ	Сервер скачивает исходный `filename`.
`photos_main.zip`	Нужен ключ с `access = 6`.

Успешный ответ:

Файл отдается через Nginx X-Accel-Redirect. Основные заголовки:

Заголовок	Значение
`Content-Type`	`application/octet-stream`
`Content-Disposition`	`attachment; filename="..."`
`Content-Length`	Размер файла
`Accept-Ranges`	`bytes`
`Cache-Control`	`public, max-age=31536000, immutable`

Примеры:

GET /download/catalog_full.json?token=test
GET /download/carsbase2_dump.sql?token=ваш_ключ
GET /download/photos_main.zip?token=ключ_с_фото

Ошибки:

{
  "error": "Bad Request",
  "message": "Недопустимое имя файла"
}

{
  "error": "Forbidden",
  "message": "Недостаточно прав для скачивания этого файла"
}

{
  "error": "Not Found",
  "message": "Файл catalog_full.json не найден"
}

Логотипы и фотографии

Логотипы марок

GET /download/logos.zip?token=xxx

Архив: logos.zip.
Формат: PNG.
Имя файла соответствует mark_id, например BMW.png.
Для темной темы используйте вариант BMW_DARK.png, если он есть в архиве.
Связь с API: marks.id.

Основные фотографии конфигураций

GET /download/photos_main.zip?token=ключ_с_фото

Архив: photos_main.zip.
Формат: JPG.
Размер: 1280×960.
Имя файла соответствует configuration_id_main.jpg.
Связь с API: configurations.id.
Для скачивания нужен ключ с доступом к фото (access = 6).

Коды ошибок

HTTP-код	`error`	Когда возникает
400	`Bad Request`	Неверный параметр, имя поля, имя файла, слишком много фильтров, неизвестное поле SQL.
401	`Unauthorized`	Не передан токен или ключ не найден.
403	`TokenExpired`	Ключ найден, но срок действия закончился.
403	`Forbidden`	Не хватает прав, например нет доступа к `photos_main.zip`.
404	`Not Found`	Файл не найден.
429	`Too Many Requests`	Превышен лимит 1000 запросов в минуту.
500	`Internal Server Error`	Ошибка сервера или базы данных.

Типовые сценарии интеграции

Построить дерево марка → модель → поколение → конфигурация → модификация

GET /marks?token=xxx&fields=id,name,cyrillic_name&sort_by=name
GET /models?token=xxx&mark_id=BMW&fields=id,name,cyrillic_name,year_from,year_to
GET /generations?token=xxx&model_id=BMW_3ER&fields=id,name,year_from,year_to
GET /configurations?token=xxx&generation_id=BMW_3ER_G20&fields=id,body_type,doors_count
GET /modifications?token=xxx&configuration_id=BMW_3ER_G20_SEDAN

Получить все данные по модификации

GET /modifications/BMW_3ER_G20_SEDAN_320I/details?token=xxx

Синхронизировать изменения

GET /modifications?token=xxx&updated_after=2026-07-01&pageSize=1000
GET /specifications?token=xxx&updated_after=2026-07-01&pageSize=1000
GET /options?token=xxx&updated_after=2026-07-01&pageSize=1000

Скачать полный набор файлов

GET /download
GET /download/carsbase2_dump.sql?token=xxx
GET /download/carsbase2_pg_dump.sql?token=xxx
GET /download/catalog_full.json?token=xxx
GET /download/catalog_full.xlsx?token=xxx
GET /download/logos.zip?token=xxx
GET /download/photos_main.zip?token=ключ_с_фото

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

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

Схема базы

Авторизация

Где нужен токен

Демо-режим

Ошибки авторизации

Общие параметры табличных маршрутов

Формат ответа табличных маршрутов

Пагинация

Offset-пагинация

Keyset-пагинация

Поля, фильтры и сортировка

Выбрать только нужные поля

Отсортировать

Получить изменения после даты

Маршруты каталога

GET /marks

GET /models

GET /generations

GET /configurations

GET /modifications

GET /specifications

GET /specifications_raw

GET /options

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

GET /modifications/:id/details

Справочники

GET /dic

GET /dic/:id

Агрегированный список марок и моделей

GET /full

Статус API

GET /status

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

GET /me

Файловые выгрузки

GET /download

GET /download/:filename

Логотипы и фотографии

Логотипы марок

Основные фотографии конфигураций

Коды ошибок

Типовые сценарии интеграции

Построить дерево марка → модель → поколение → конфигурация → модификация

Получить все данные по модификации

Синхронизировать изменения

Скачать полный набор файлов

Песочница API