{"openapi":"3.1.0","info":{"title":"encarapi","version":"1.0.0","description":"Real-time Korean used-car data from the full Encar inventory, served as clean JSON.\n\nFilter the whole catalog with simple **English** query parameters (or the raw Encar `q` grammar). Add `lang=en` to receive every value in English. Discover all valid filter values at `/api/enums`.\n\n## Data freshness and caching\n\nThe full catalog is refreshed every day, the newest listings are picked up every 2 hours, and sold cars are removed hourly.\n\nRecommended cache times:\n- `/api/enums`, the taxonomy CSVs and `/api/nav`: 24 hours (makes, models, badges and filter values barely change)\n- `/api/catalog` listings: 1 to 2 hours (new listings are picked up every 2 hours)\n- `/api/vehicle/{id}` details: 24 hours (a listing's specs are static; it only drops out when sold)\n\nServe listings from your own database and refresh on this cadence rather than calling live on every user click. Fair use applies; there is no strict per-minute cap.","contact":{"name":"encarapi","url":"https://encarapi.com"}},"servers":[{"url":"https://api.encarapi.com","description":"Production"}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"tags":[{"name":"Catalog","description":"Search & list vehicles"},{"name":"Vehicle","description":"Per-vehicle detail, history & inspection"},{"name":"Discovery","description":"Filter facets & valid values"},{"name":"Taxonomy","description":"Downloadable make/model/badge lists (CSV). Fetch once, cache for a day, and drive your dropdowns from these - no offline mapping, no per-click facet calls."}],"paths":{"/api/catalog":{"get":{"tags":["Catalog"],"summary":"Search & list vehicles","description":"Without filters, returns the newest listings (paginated). Add `count=true` for the total match count.","parameters":[{"name":"manufacturer","in":"query","description":"Brand. Comma-separated = OR.","schema":{"type":"string"},"example":"bmw"},{"name":"model_group","in":"query","description":"Model line (English name or Korean token).","schema":{"type":"string"},"example":"3-series"},{"name":"model","in":"query","description":"Specific generation.","schema":{"type":"string"}},{"name":"fuel","in":"query","description":"Fuel type.","schema":{"type":"string","enum":["gasoline","diesel","hybrid","diesel-hybrid","lpg-hybrid","gasoline-lpg","cng","electric","lpg","hydrogen","other"]},"example":"diesel"},{"name":"transmission","in":"query","description":"Transmission type.","schema":{"type":"string","enum":["automatic","manual","cvt","semi-automatic","other"]},"example":"automatic"},{"name":"color","in":"query","description":"Exterior / paint color.","schema":{"type":"string","enum":["white","black","gray","blue","silver","silver-gray","pearl","red","sky-blue","green","dark-green","light-green","brown","yellow","orange","purple","maroon","turquoise","gold","pink"]},"example":"black"},{"name":"seat_color","in":"query","description":"Interior / seat color.","schema":{"type":"string","enum":["black","brown","beige","gray","red","white","blue","green","orange","yellow"]},"example":"beige"},{"name":"category","in":"query","description":"Body category.","schema":{"type":"string","enum":["suv","rv","large","midsize","compact","small","kei","van","light-van","truck","sports","other"]},"example":"suv"},{"name":"seats","in":"query","description":"Number of seats. Comma = OR (e.g. 5,7).","schema":{"type":"string"},"example":"7,9"},{"name":"min_seats","in":"query","description":"Minimum seats.","schema":{"type":"integer"}},{"name":"max_seats","in":"query","description":"Maximum seats.","schema":{"type":"integer"}},{"name":"options","in":"query","description":"Equipment codes; the car must have all listed. Comma-separated.","schema":{"type":"string"},"example":"001,024"},{"name":"min_price","in":"query","description":"Min price in 만원 (1 = 10,000 KRW).","schema":{"type":"integer"},"example":2000},{"name":"max_price","in":"query","description":"Max price in 만원 (1 = 10,000 KRW).","schema":{"type":"integer"},"example":5000},{"name":"min_year","in":"query","description":"Min model year (4-digit).","schema":{"type":"integer"},"example":2021},{"name":"max_year","in":"query","description":"Max model year (4-digit).","schema":{"type":"integer"}},{"name":"min_mileage","in":"query","description":"Min mileage in km.","schema":{"type":"integer"}},{"name":"max_mileage","in":"query","description":"Max mileage in km.","schema":{"type":"integer"},"example":100000},{"name":"lang","in":"query","description":"Set to 'en' to receive all values in English.","schema":{"type":"string","enum":["en"]},"example":"en"},{"name":"q","in":"query","description":"Advanced: raw Encar q-grammar (alternative to the flat parameters above).","schema":{"type":"string"}},{"name":"badge_group","in":"query","schema":{"type":"string"},"example":"c43-amg-4matic-coupe","description":"Badge / trim group - this is where the body-style split lives (Coupe vs Sedan vs Cabriolet). Use a value from /api/taxonomy/badges.csv or /api/nav; filter on this instead of parsing the title."},{"name":"badge","in":"query","schema":{"type":"string"},"description":"Exact badge (finest trim level), value from /api/nav."},{"name":"drivetrain","in":"query","schema":{"type":"string"},"example":"4wd","description":"Drivetrain (e.g. 2wd / 4wd). Values from /api/nav."},{"name":"model_search","in":"query","schema":{"type":"string"},"example":"s63 coupe","description":"Cross-brand free-text model search. \";\"-separated phrases are OR-combined (e.g. \"s63 coupe;m5\"). Matches make/model/badge names. See also GET /api/model-search for autocomplete."},{"name":"min_ps","in":"query","schema":{"type":"integer"},"description":"Minimum engine power in PS."},{"name":"max_ps","in":"query","schema":{"type":"integer"},"description":"Maximum engine power in PS."},{"name":"max_owners","in":"query","schema":{"type":"integer"},"example":1,"description":"Maximum number of previous owners."},{"name":"frame_clean","in":"query","schema":{"type":"boolean"},"example":true,"description":"true = only accident-free cars (clean chassis frame)."},{"name":"no_damage_cost","in":"query","schema":{"type":"boolean"},"description":"true = only cars with zero insurance-reported repair cost."},{"name":"no_repairs","in":"query","schema":{"type":"boolean"},"description":"true = only cars with no recorded panel repairs."},{"name":"has_photos","in":"query","schema":{"type":"boolean"},"description":"true = only listings that have photos."},{"name":"sort","in":"query","description":"Sort order.","schema":{"type":"string","enum":["newest","price_asc","price_desc","mileage_asc","mileage_desc","year_desc","year_asc"],"default":"newest"},"example":"price_asc"},{"name":"page","in":"query","description":"Page number (1-based).","schema":{"type":"integer","default":1},"example":1},{"name":"limit","in":"query","description":"Results per page (1-1000).","schema":{"type":"integer","default":20},"example":25},{"name":"count","in":"query","description":"Include the total match count.","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/enums":{"get":{"tags":["Discovery"],"summary":"Valid filter values","description":"Every valid English value per filter field, with live counts. Ideal for building filter menus.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnumsResponse"}}}}}}},"/api/nav":{"get":{"tags":["Discovery"],"summary":"Filter facets (iNav tree)","description":"Available facet values with counts for the current selection. Respects `lang=en`.","parameters":[{"name":"manufacturer","in":"query","description":"Brand. Comma-separated = OR.","schema":{"type":"string"},"example":"bmw"},{"name":"model_group","in":"query","description":"Model line (English name or Korean token).","schema":{"type":"string"},"example":"3-series"},{"name":"model","in":"query","description":"Specific generation.","schema":{"type":"string"}},{"name":"fuel","in":"query","description":"Fuel type.","schema":{"type":"string","enum":["gasoline","diesel","hybrid","diesel-hybrid","lpg-hybrid","gasoline-lpg","cng","electric","lpg","hydrogen","other"]},"example":"diesel"},{"name":"transmission","in":"query","description":"Transmission type.","schema":{"type":"string","enum":["automatic","manual","cvt","semi-automatic","other"]},"example":"automatic"},{"name":"color","in":"query","description":"Exterior / paint color.","schema":{"type":"string","enum":["white","black","gray","blue","silver","silver-gray","pearl","red","sky-blue","green","dark-green","light-green","brown","yellow","orange","purple","maroon","turquoise","gold","pink"]},"example":"black"},{"name":"seat_color","in":"query","description":"Interior / seat color.","schema":{"type":"string","enum":["black","brown","beige","gray","red","white","blue","green","orange","yellow"]},"example":"beige"},{"name":"category","in":"query","description":"Body category.","schema":{"type":"string","enum":["suv","rv","large","midsize","compact","small","kei","van","light-van","truck","sports","other"]},"example":"suv"},{"name":"seats","in":"query","description":"Number of seats. Comma = OR (e.g. 5,7).","schema":{"type":"string"},"example":"7,9"},{"name":"min_seats","in":"query","description":"Minimum seats.","schema":{"type":"integer"}},{"name":"max_seats","in":"query","description":"Maximum seats.","schema":{"type":"integer"}},{"name":"options","in":"query","description":"Equipment codes; the car must have all listed. Comma-separated.","schema":{"type":"string"},"example":"001,024"},{"name":"min_price","in":"query","description":"Min price in 만원 (1 = 10,000 KRW).","schema":{"type":"integer"},"example":2000},{"name":"max_price","in":"query","description":"Max price in 만원 (1 = 10,000 KRW).","schema":{"type":"integer"},"example":5000},{"name":"min_year","in":"query","description":"Min model year (4-digit).","schema":{"type":"integer"},"example":2021},{"name":"max_year","in":"query","description":"Max model year (4-digit).","schema":{"type":"integer"}},{"name":"min_mileage","in":"query","description":"Min mileage in km.","schema":{"type":"integer"}},{"name":"max_mileage","in":"query","description":"Max mileage in km.","schema":{"type":"integer"},"example":100000},{"name":"lang","in":"query","description":"Set to 'en' to receive all values in English.","schema":{"type":"string","enum":["en"]},"example":"en"},{"name":"q","in":"query","description":"Advanced: raw Encar q-grammar (alternative to the flat parameters above).","schema":{"type":"string"}},{"name":"badge_group","in":"query","schema":{"type":"string"},"example":"c43-amg-4matic-coupe","description":"Badge / trim group - this is where the body-style split lives (Coupe vs Sedan vs Cabriolet). Use a value from /api/taxonomy/badges.csv or /api/nav; filter on this instead of parsing the title."},{"name":"badge","in":"query","schema":{"type":"string"},"description":"Exact badge (finest trim level), value from /api/nav."},{"name":"drivetrain","in":"query","schema":{"type":"string"},"example":"4wd","description":"Drivetrain (e.g. 2wd / 4wd). Values from /api/nav."},{"name":"model_search","in":"query","schema":{"type":"string"},"example":"s63 coupe","description":"Cross-brand free-text model search. \";\"-separated phrases are OR-combined (e.g. \"s63 coupe;m5\"). Matches make/model/badge names. See also GET /api/model-search for autocomplete."},{"name":"min_ps","in":"query","schema":{"type":"integer"},"description":"Minimum engine power in PS."},{"name":"max_ps","in":"query","schema":{"type":"integer"},"description":"Maximum engine power in PS."},{"name":"max_owners","in":"query","schema":{"type":"integer"},"example":1,"description":"Maximum number of previous owners."},{"name":"frame_clean","in":"query","schema":{"type":"boolean"},"example":true,"description":"true = only accident-free cars (clean chassis frame)."},{"name":"no_damage_cost","in":"query","schema":{"type":"boolean"},"description":"true = only cars with zero insurance-reported repair cost."},{"name":"no_repairs","in":"query","schema":{"type":"boolean"},"description":"true = only cars with no recorded panel repairs."},{"name":"has_photos","in":"query","schema":{"type":"boolean"},"description":"true = only listings that have photos."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/model-search":{"get":{"tags":["Discovery"],"summary":"Model autocomplete","description":"Cross-brand free-text suggestions for a search box. Given text like \"s63\" or \"m3 coupe\", returns distinct make / model / badge matches with counts, each with an English label. Use the returned values as ?model_search= (or ?manufacturer=/?model_group=) on /api/catalog.","parameters":[{"name":"search","in":"query","required":true,"schema":{"type":"string"},"example":"s63 coupe","description":"Free-text query."},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Max suggestions (max 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/taxonomy/makes.csv":{"get":{"tags":["Taxonomy"],"summary":"All makes (CSV)","description":"Every make with active-listing counts as a CSV download (columns: make, make_ko, count). Fetch once, cache for a day, drive your make dropdown from this - no offline mapping.","responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/taxonomy/models.csv":{"get":{"tags":["Taxonomy"],"summary":"All models (CSV)","description":"Every make + model with counts (columns: make, model, model_ko, count). Cache and drive the model dropdown client-side.","responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/taxonomy/badges.csv":{"get":{"tags":["Taxonomy"],"summary":"All badges (CSV)","description":"Every make + model + badge with counts (columns: make, model, badge, badge_ko, count). The badge level carries the body-style split (e.g. Coupe vs Sedan vs Cabriolet) - filter on it directly instead of parsing the title string.","responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/vehicle/{id}":{"get":{"tags":["Vehicle"],"summary":"Vehicle detail","description":"Full specification, photos and equipment for one listing. `{id}` is the `Id` from the catalog.\n\nAlso includes `spec.powerPs` / `spec.powerKw` (engine power) when available for the listing - sourced from JATO, not from Encar's own detail payload, so it may be absent for some vehicles.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The Id from the catalog response.","example":"39781121"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/record/{id}":{"get":{"tags":["Vehicle"],"summary":"Accident & ownership record","description":"Full insurance accident and ownership history for one vehicle. Includes accident counts and repair costs for damage to this car and for damage it caused to others, the number of owner and plate changes, total-loss, flood and theft events, and a dated list of every insurance claim. `{id}` is the `Id` from the catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The Id from the catalog response.","example":"39781121"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/inspection/{id}":{"get":{"tags":["Vehicle"],"summary":"Inspection report","description":"Official pre-sale inspection report for one vehicle. `master` holds the certified summary (VIN, mileage, accident and simple-repair flags, tuning, recall, engine and transmission checks), while `outers` and `inners` list per-panel condition codes and `images` the inspection photos. `{id}` is the `Id` from the catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The Id from the catalog response.","example":"39781121"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InspectionResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Your API key (alternative to the header)."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key."},"NotFound":{"description":"Listing not found (sold or removed)."},"RateLimited":{"description":"Rate limit exceeded."}},"schemas":{"CatalogResponse":{"type":"object","properties":{"Count":{"type":"integer","description":"Total matches (only when count=true).","example":687},"SearchResults":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}}},"CatalogItem":{"type":"object","description":"Raw Korean fields are always present; the *English companions give the English value. With lang=en the main fields are English and the *English duplicates are omitted.","properties":{"Id":{"type":"string","example":"39781121"},"Manufacturer":{"type":"string","example":"BMW"},"ManufacturerEnglish":{"type":"string","example":"BMW"},"Model":{"type":"string","example":"5시리즈"},"ModelEnglish":{"type":"string","example":"5-Series"},"Badge":{"type":"string","example":"520d"},"BadgeEnglish":{"type":"string","example":"520d"},"FuelType":{"type":"string","example":"디젤"},"FuelTypeEnglish":{"type":"string","example":"diesel"},"Year":{"type":"integer","description":"YYYYMM","example":202105},"Price":{"type":"integer","description":"In 만원 (10,000 KRW).","example":4890},"Mileage":{"type":"integer","description":"km","example":38200},"PowerPs":{"type":["integer","null"],"description":"Engine power in PS (JATO-sourced; absent when not available for this listing).","example":245},"PowerKw":{"type":["integer","null"],"description":"Engine power in kW (JATO-sourced; absent when not available for this listing).","example":180},"Photos":{"type":"array","items":{"type":"object","properties":{"location":{"type":"string"}}}}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer"}}},"EnumsResponse":{"type":"object","properties":{"fuel":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}},"transmission":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}},"color":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}},"seat_color":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}},"category":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/EnumValue"}}}},"AccidentEvent":{"type":"object","description":"A single insurance-reported repair event. All costs are in KRW.","properties":{"date":{"type":"string","format":"date","description":"Date of the claim.","example":"2024-01-23"},"type":{"type":"string","description":"Claim type code (1 = damage to own car, 2 = damage caused to others, etc.).","example":"3"},"partCost":{"type":"integer","description":"Parts cost, KRW.","example":0},"laborCost":{"type":"integer","description":"Labor cost, KRW.","example":72630},"paintingCost":{"type":"integer","description":"Painting cost, KRW.","example":201089},"insuranceBenefit":{"type":"integer","description":"Total insurance payout for this event, KRW.","example":300000}}},"RecordResponse":{"type":"object","description":"Official insurance accident and ownership history for one vehicle.","properties":{"accidentCnt":{"type":"integer","description":"Total number of insurance-reported accidents.","example":2},"myAccidentCnt":{"type":"integer","description":"Insurance claims for damage to THIS vehicle.","example":1},"myAccidentCost":{"type":"integer","description":"Total repair payout for damage to this vehicle, KRW.","example":1748300},"otherAccidentCnt":{"type":"integer","description":"Claims where this vehicle damaged another party.","example":1},"otherAccidentCost":{"type":"integer","description":"Total payout for damage this vehicle caused to others, KRW.","example":273719},"ownerChangeCnt":{"type":"integer","description":"Number of ownership changes.","example":2},"ownerChanges":{"type":"array","items":{"type":"string","format":"date"},"description":"Date of each ownership change (newest first).","example":["2026-02-19","2021-07-08"]},"carNoChangeCnt":{"type":"integer","description":"Number of license-plate changes.","example":0},"totalLossCnt":{"type":"integer","description":"Times the vehicle was written off as a total loss.","example":0},"totalLossDate":{"type":["string","null"],"description":"Date of the total-loss event, if any."},"floodTotalLossCnt":{"type":"integer","description":"Flood total-loss events.","example":0},"floodPartLossCnt":{"type":["integer","null"],"description":"Flood partial-loss events.","example":null},"floodDate":{"type":["string","null"],"description":"Date of the flood-damage event, if any."},"robberCnt":{"type":"integer","description":"Number of recorded theft events.","example":0},"robberDate":{"type":["string","null"],"description":"Date of the theft event, if any."},"use":{"type":"string","description":"Usage code ('1' = private, '2' = commercial/business, '3' = government).","example":"2"},"business":{"type":"integer","description":"Whether the car was ever used commercially (1) or not (0).","example":0},"firstDate":{"type":"string","format":"date","description":"First registration date of the vehicle.","example":"2017-07-31"},"regDate":{"type":"string","description":"Timestamp when this insurance record was generated."},"accidents":{"type":"array","description":"Dated list of every insurance claim with itemized costs.","items":{"$ref":"#/components/schemas/AccidentEvent"}}}},"InspectionMaster":{"type":"object","description":"Certified summary of the official government inspection.","properties":{"accdient":{"type":"boolean","description":"Whether the inspection flags accident history (note: the Encar field is misspelled \"accdient\").","example":false},"simpleRepair":{"type":"boolean","description":"Whether only simple repairs (e.g. paint) were found.","example":false},"supplyNum":{"type":"string","description":"Inspection certificate number."},"registrationDate":{"type":"string","description":"Date the inspection was registered."},"detail":{"type":"object","description":"Full inspection detail: vin, mileage, waterlog, tuning, recall, engine and transmission checks, serious-damage types, painted panels, main options, and validity dates."}}},"InspectionResponse":{"type":"object","description":"Official pre-sale inspection report for one vehicle.","properties":{"vehicleId":{"type":"string","description":"Encar vehicle id this report belongs to."},"master":{"$ref":"#/components/schemas/InspectionMaster"},"outers":{"type":"array","description":"Exterior panel condition codes (paint, dent, replacement). Empty when no exterior issues.","items":{"type":"object"}},"inners":{"type":"array","description":"Interior / structural frame panel condition codes.","items":{"type":"object"}},"images":{"type":"array","description":"Inspection photo references.","items":{"type":"object"}},"price":{"type":["object","null"],"description":"Assessed-value data, when provided by the inspector."},"etcs":{"type":"array","description":"Additional inspector notes.","items":{"type":"object"}},"formats":{"type":"array","description":"Report format metadata.","items":{"type":"object"}},"inspectionSource":{"type":"string","description":"Origin of the inspection report."},"directManagement":{"type":"boolean","description":"Whether the listing is directly managed by Encar."}}}}}}