문서

기본 URL

모든 API 요청은 다음 기본 URL로 이루어집니다:

https://api.encarapi.com

예를 들어, 매물을 가져오려면:

GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true

인증

API 키를 사용하여 요청을 인증합니다. 쿼리 매개변수 또는 Authorization 헤더로 전달하세요.

# Send your API key in the x-api-key header (recommended):
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true"

# The api_key query parameter also works:
GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true&api_key=YOUR_API_KEY

5일 체험

3개 마켓플레이스(엔카, KB차차차, 케이카) 전체와 함께 변경 피드(최근 7일), 일괄 조회(하루 1,000개 id), 아카이브 미리보기(하루 삭제된 매물 100건)를 포함하여 5일 동안 API를 체험해 보십시오. 카탈로그 총 100,000행, 상세 조회 총 2,000건(하루 최대 1,000건). 참조 데이터 다운로드(CSV)는 유료 플랜에 포함됩니다. 전체 카탈로그 내보내기는 Business 플랜부터 제공됩니다. 체험 기간이 끝나면 구독은 Starter 플랜(월 €149)으로 자동 갱신됩니다 - 5일 차 이전에 언제든지 취소할 수 있습니다.

러시아어 값 (lang=ru)

lang=en을 받는 모든 엔드포인트는 lang=ru도 받습니다. 표시용 값은 러시아어로 오고 나머지(ID, 코드, 가격, 숫자, 필드명)는 그대로입니다. 러시아어 라벨이 없는 값은 영어로 반환됩니다. 러시아어 라벨은 시간이 지나며 다듬어질 수 있으니 데이터는 라벨이 아닌 ID와 코드로 연결하세요.

• 번역 대상: 연료, 변속기, 구동 방식, 외장 및 내장 색상, 차급, 판매 유형, 지역 및 도시명, 옵션명, 트림명에 들어가는 일반 단어 (Diesel -> дизель, 7-Seater -> 7 мест). 모델 세대: Carnival 4 Gen -> Carnival 4 поколение. 브랜드, 모델, 트림명은 러시아 중고차 사이트처럼 라틴 문자로 유지됩니다.
• 필터는 러시아어 값도 받습니다: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. 영어 값도 계속 사용할 수 있습니다.
• /api/enums?lang=ru는 모든 값에 nameRu를 추가하고 drivetrain과 sell_type 값도 나열합니다. /api/nav?lang=ru는 러시아어 DisplayValue를 반환하며, Value는 필터용 영어 코드로 유지됩니다. 참조 CSV에 lang=ru를 붙이면 마지막 열 뒤에 러시아어 이름 열이 추가됩니다.
• /api/vehicle/{id}?lang=ru와 bulk 엔드포인트는 Encar의 spec 값, category 이름, optionsDecoded 이름을 러시아어로 반환하고, KB차차차 매물은 카탈로그와 같은 형태로 반환합니다.
• /api/catalog/export?lang=ru는 라벨 열만 러시아어인 같은 파일입니다. 열 순서와 다른 모든 열은 바뀌지 않습니다.
• 번역되지 않는 항목: 성능점검 보고서, 보험 이력, 엔카진단, 엔카 차량이력, K Car 상세 데이터, Encar 옵션 패키지(매물의 자유 텍스트), 트럭 및 굴삭기 엔드포인트(lang=ru에도 영어로 응답).

# Russian values, filtered with Russian values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?fuel=дизель&city=Сувон&lang=ru&count=true"

# Filter values with their Russian labels (nameRu)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/enums?lang=ru"

독일어 값 (lang=de)

lang=de는 lang=ru와 같은 방식으로 동작합니다. 표시용 값은 독일어로 오고 나머지(ID, 코드, 가격, 숫자, 필드명)는 그대로입니다. 독일어 라벨이 없는 값은 영어로 반환됩니다.

• 번역 대상: 연료, 변속기, 구동 방식, 색상, 차급, 판매 유형, 옵션명, 그리고 독일어 테이블에 있는 모델명과 트림명 (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). 지역명은 영어 이름, 도시명은 영어로 유지됩니다.
• 필터는 독일어 값도 받습니다: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. 독일어 모델명은 페이스리프트를 묶을 수 있습니다: Carnival 4. Generation은 Carnival 4 Gen과 The New Carnival 4 Gen을 모두 포함합니다.
• 목록, 상세, bulk, 내보내기는 lang=ru와 같습니다: /api/enums와 /api/taxonomy/option-packages에 nameDe, /api/nav에 독일어 DisplayValue, 참조 CSV에 *_de 열, 내보내기는 catalog_export_de.csv. 번역되지 않는 항목도 lang=ru와 같습니다.

# German values, filtered with German values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=Mercedes-Benz&model_group=C-Klasse&fuel=Benzin&lang=de&count=true"

세 개의 마켓플레이스, 하나의 API

이 API는 한국 3대 중고차 마켓플레이스의 실시간 매물을 제공합니다. 모든 엔드포인트는 기본적으로 엔카 매물을 반환하므로 기존 연동은 변경 없이 그대로 동작합니다. 나머지 두 곳은 source 파라미터로 선택해 사용할 수 있습니다.

소스 선택

source는 /api/catalog, /api/nav, /api/enums, /api/model-search, /api/catalog/export, /api/catalog/changes 및 분류 체계 CSV에서 사용할 수 있습니다.

# All three marketplaces, English values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=all&manufacturer=bmw&fuel=diesel&lang=en&count=true"

# K Car only
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=kcar&manufacturer=hyundai&lang=en"

# One KB Chachacha vehicle
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/vehicle/kbc:12345678?lang=en"

source를 지정하면 모든 항목에 Source 필드가 포함됩니다. 엔카 id는 일반 숫자 그대로입니다. KB차차차와 케이카 id에는 접두사(kbc:..., kcar:...)가 붙습니다 - 변경 없이 그대로 /api/vehicle/{id}에 전달하세요. lang=en을 사용하면 세 마켓플레이스 모두의 모델명과 트림명이 영어로 반환됩니다.

딜러는 같은 차량을 엔카와 KB차차차에 함께 등록하는 경우가 많습니다. KB차차차 매물은 차량번호로, KB차차차가 차량번호를 공개하지 않는 경우에는 최초등록 연월, 주행거리, 가격으로 활성 엔카 매물과 매칭됩니다. 매칭은 엔카와 KB차차차 카탈로그 순회가 끝날 때마다 하루에 여러 번 다시 계산됩니다. 매칭된 KB차차차 매물은 source 지정 여부와 관계없이(source=kbc만 지정해도) /api/catalog, /api/catalog/export 및 기타 카탈로그 엔드포인트에서 반환되지 않으므로 같은 차량이 두 번 나타나지 않습니다. 엔카가 포함되면 엔카 매물로 반환됩니다.

/api/catalog/changes?source=kbc와 /api/vehicle/kbc:{id}에서는 이 매물에 IsDuplicate: true와 DuplicateOf(엔카 매물 ID, 숫자 문자열)가 포함됩니다. 엔카 아이템과 마찬가지로 두 필드는 true일 때만 존재합니다. 표시가 설정되거나 해제되면 변경 피드는 changedFields에 duplicate가 포함된 updated 이벤트를 기록합니다. 로컬 사본을 /api/catalog와 일치시키려면 IsDuplicate: true로 들어온 KB차차차 아이템은 삭제하고, 이 필드 없이 업데이트가 들어오면 다시 추가하세요.

변경 피드는 호출당 하나의 소스(encar, kbc 또는 kcar)를 받으며 소스마다 별도의 커서를 유지합니다.

마켓플레이스별 제공 범위

모든 마켓플레이스가 모든 필드를 공개하는 것은 아닙니다.

• KB차차차는 일부 매물에 대해 좌석 수를 공개합니다.
• KB차차차 상세 = 카탈로그 항목에 공개 이력 블록(사고 여부, 전손, 침수, 영업용 사용, 저당, 프레임 및 패널 진단)을 더한 것입니다. 모든 KB차차차 항목에는 InsuranceClaims(매물 페이지에 표시되는 보험사고 이력 건수)도 포함됩니다. 상세에는 InspectionReportUrl과 InspectionReportType도 포함됩니다. KB차차차가 해당 차량에 보여 주는 성능점검기록부입니다(link = 점검업체 웹사이트의 기록부, scan = 매물 페이지의 스캔 이미지만 있음, null = 아직 알 수 없음). InspectionAvailable이 true이면 GET /api/inspection/kbc:{id}가 이 기록부를 엔카 성능점검기록부와 같은 형식의 구조화된 데이터(master, outers, inners, images)로 반환하며, source 블록도 함께 제공합니다. 기록부가 연결된 KB차차차 매물 약 5건 중 2건이 대상입니다.
• 케이카에는 별도의 보고서 문서가 없으며, 사고 횟수, 보험금 지급 내역, 소유자 변경은 차량 상세에 포함됩니다.

마켓플레이스가 제공하지 않는 필드로 필터링하면 해당 마켓플레이스의 차량은 결과에서 제외됩니다. 예: frame_clean=true와 source=all을 함께 사용하면 엔카와 케이카 매물만 반환됩니다.

API 엔드포인트

한국 차량 데이터에 접근하기 위한 모든 사용 가능한 엔드포인트.

드롭다운 데이터(CSV)

제조사, 모델, 배지 목록을 CSV로 다운로드해 캐시하고 이를 바탕으로 드롭다운을 구성하세요 - 클릭할 때마다 하는 패싯 호출이나 오프라인 매핑이 필요 없습니다. 각 파일에는 개수 열이 포함되며, 배지 파일에는 바디 스타일 구분(Coupe／Sedan／Cabrio)이 포함됩니다.

자주 묻는 질문