Поле extra — блок данных рынка encar

Поле extra в ответах Union API по рынку encar содержит два набора данных о конкретном автомобиле:

• risk_data — история автомобиля: ДТП, залоги, аресты, угон, затопление, полная гибель, смены владельцев и номеров, характер использования;
• options — заводские опции в виде кодов;
• блок таможни — расчёт пошлины/акциза/утильсбора (может отсутствовать).

Все данные относятся к самому автомобилю (его истории и комплектации), а не к объявлению.

Как получить

Запросите поле extra в списке fields:

GET /api/v2/cars?market=encar&fields=id,brand,model,year,price,extra&limit=10

Значение extra приходит строкой с JSON (не вложенным объектом). Перед использованием его нужно распарсить: JSON.parse(row.extra). В CSV-выгрузках extra также лежит одной колонкой-строкой с JSON, а разделитель колонок — ; (кавычки внутри значений удвоены, RFC-4180).

Поле attributes — это ключи фильтрации (status, total_price_rub, recycling_fee_rub) и для отображения в карточке не предназначено.

Структура

extra = { risk_data, options, <блок таможни> }

1. risk_data (объект)

Ключи pledge_count, seizing_count, is_rental могут отсутствовать — это значит «нет данных», а не «нет залогов/арестов». Отражайте это различие в интерфейсе.

1.1 accidents[] — элемент

Массив приходит по убыванию даты, но надёжнее сортировать самостоятельно (date desc).

Коды type (кодировка Encar):

Семантика кодов предварительная (из справочника Encar, уточняется). Если тип не критичен, для интерфейса безопаснее показывать сам факт и стоимость ДТП, чем опираться на код.

1.2 accident_summary — объект

my_car_cnt + other_car_cnt не равно cnt: одно ДТП может попасть в обе категории. Не выводите одну величину из другой.

1.3 car_changes[] — элемент

1.4 flood / theft / total_loss

Счётчики — всегда int: 0 означает «не было». date может отсутствовать.

1.5 ownership

1.6 usage

2. options — объект (не массив)

{ "type": "CAR",
  "standard": ["001","002"],
  "choice":   [],
  "tuning":   ["023","026"],
  "etc":      ["..."] }

standard/choice/tuning — числовые коды из справочника опций Encar, не человекочитаемые названия. Поле etc — свободный текст (корейский).

Расшифровка кодов

Коды 3-значные (standard, tuning) расшифровываются встроенным справочником Union API:

GET /api/v2/cars/options/dictionary?market=encar
Authorization: Bearer <token>

Ответ — карта option_code → {name_ru, name_en} (62 записи, коды 001–097). Данные справочные, бесплатные, из баланса не списываются. Используйте name_ru для отображения, name_en — для англоязычного интерфейса.

Коды 4-значные (choice, 1000+) справочником НЕ покрыты — их отображение клиент реализует самостоятельно.

3. Блок таможни — верхний уровень extra (не в risk_data)

Блок может отсутствовать целиком, если расчёт для автомобиля не выполнен (в выборке он есть примерно у 15 % объявлений). Отсутствие блока — норма, а не ошибка.

4. Как интерпретировать и отображать

1. Экранируйте строковые значения перед вставкой в HTML: etc, plate_no и любые другие текстовые поля приходят из внешних данных.
2. null/отсутствие ключа ≠ false/0. «Данных нет» и «чисто» — разные состояния. Не показывайте «0 ДТП» там, где данных просто нет.
3. Служебные метки времени не для показа. Поле first_seen_at приходит в ответе по умолчанию, но это внутренняя метка первой регистрации объявления — в карточке её отображать не нужно.
4. is_rental — это прокат, а не залог. Залог и арест — это pledge_count/seizing_count.
5. Автомобили-дубли (в attributes.status = DUPLICATION) несут extra оригинала — это ожидаемое поведение.

5. Пример (реальные данные)

{
  "risk_data": {
    "is_rental": false,
    "pledge_count": 0,
    "seizing_count": 0,
    "insurance_gaps": ["201909~202107", null, null, null, null],
    "accidents": [
      {"date": "2019-06-17", "type": "1", "part_cost": 586682,
       "labor_cost": 518298, "painting_cost": 704598,
       "insurance_benefit": 1590000}
    ],
    "accident_summary": {"cnt": 4, "my_car_cnt": 4, "my_car_cost": 5793633,
                         "other_car_cnt": 2, "other_car_cost": 5225224},
    "car_changes": [{"date": "2011-09-08", "plate_no": "34누XXXX"}],
    "flood": {"total_loss_cnt": 0, "partial_loss_cnt": 0},
    "theft": {"cnt": 0},
    "total_loss": {"cnt": 0},
    "ownership": {"changes": ["2025-11-13", "2023-12-28"], "change_cnt": 2},
    "usage": {"type_code": "2", "is_business": false,
              "is_government": false, "use_history": ["2"]}
  },
  "options": {
    "type": "CAR",
    "standard": ["001", "004", "005"],
    "choice": ["1004", "1003"],
    "tuning": ["024"],
    "etc": []
  }
}