Documentatie

Basis-URL

Alle API-verzoeken worden gedaan naar de volgende basis-URL:

https://api.encarapi.com

Bijvoorbeeld, om aanbiedingen op te halen:

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

Authenticatie

Authenticeer uw verzoeken met een API-sleutel. Geef deze door als queryparameter of via de Authorization-header.

# 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

Proefperiode van 5 dagen

Test de API 5 dagen met alle drie de marktplaatsen (Encar, KB Chachacha, K Car), inclusief wijzigingssync (laatste 7 dagen), bulkopvragingen (1.000 ids per dag) en een archiefvoorbeeld (100 verwijderde advertenties per dag). 100.000 catalogusrijen en 2.000 detailopvragingen in totaal (max. 1.000 per dag). De referentiedownloads (CSV) horen bij de betaalde plannen. De volledige catalogusexport begint bij Business. Daarna loopt je abonnement door op het Starter-plan voor 149 €/maand - tot dag 5 op elk moment opzegbaar.

Russische waarden (lang=ru)

Elk endpoint dat lang=en accepteert, accepteert ook lang=ru: weergavewaarden komen in het Russisch, al het andere blijft gelijk (ids, codes, prijzen, getallen, veldnamen). Een waarde zonder Russisch label valt terug op Engels. Russische labels kunnen in de loop van de tijd worden verfijnd, koppel je data dus op ids en codes, niet op labels.

• Vertaald: brandstof, transmissie, aandrijving, exterieur- en interieurkleur, carrosserieklasse, verkoopsoort, regio- en plaatsnamen, optienamen en de algemene woorden in uitvoeringsnamen (Diesel -> дизель, 7-Seater -> 7 мест). Modelgeneraties: Carnival 4 Gen -> Carnival 4 поколение. Merk-, model- en uitvoeringsnamen blijven in Latijns schrift, zoals op Russische automarktplaatsen.
• Filters accepteren ook de Russische waarden: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. De Engelse waarden blijven werken.
• /api/enums?lang=ru voegt nameRu toe aan elke waarde en toont de waarden voor drivetrain en sell_type. /api/nav?lang=ru geeft een Russische DisplayValue; Value blijft de Engelse code om op te filteren. De referentie-CSV's krijgen met lang=ru de Russische naam als extra kolom na de laatste.
• /api/vehicle/{id}?lang=ru en het bulk-endpoint geven de Encar-spec-waarden, de category-namen en de optionsDecoded-namen in het Russisch, en KB Chachacha-items zoals in de catalogus.
• /api/catalog/export?lang=ru is hetzelfde bestand met de labelkolommen in het Russisch; kolomvolgorde en alle andere kolommen blijven ongewijzigd.
• Niet vertaald: keuringsrapporten, verzekeringshistorie, Encar-diagnoses, Encar-voertuighistories, K Car-detaildata, Encar-optiepakketten (vrije tekst uit de advertentie) en de endpoints voor vrachtwagens en graafmachines (die antwoorden bij lang=ru in het Engels).

# 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"

Duitse waarden (lang=de)

lang=de werkt zoals lang=ru: weergavewaarden komen in het Duits, al het andere blijft gelijk (ids, codes, prijzen, getallen, veldnamen). Een waarde zonder Duits label valt terug op Engels.

• Vertaald: brandstof, transmissie, aandrijving, kleuren, carrosserieklasse, verkoopsoort, optienamen en model- en uitvoeringsnamen uit onze Duitse tabellen (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). Regio's houden de Engelse naam, plaatsnamen blijven Engels.
• Filters accepteren ook de Duitse waarden: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. Duitse modelnamen kunnen facelifts samenvoegen: Carnival 4. Generation omvat Carnival 4 Gen en The New Carnival 4 Gen.
• Lijsten, detail, bulk en export werken zoals bij lang=ru: nameDe in /api/enums en /api/taxonomy/option-packages, een Duitse DisplayValue in /api/nav, *_de-kolommen in de referentie-CSV's, catalog_export_de.csv voor de export. Niet vertaald: hetzelfde als bij 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"

Drie marktplaatsen, één API

De API levert live advertenties van de drie grote Koreaanse marktplaatsen voor gebruikte auto's. Elk eindpunt retourneert standaard Encar, dus bestaande integraties blijven ongewijzigd werken. De andere twee zijn opt-in via de parameter source.

Bronnen selecteren

source wordt geaccepteerd door /api/catalog, /api/nav, /api/enums, /api/model-search, /api/catalog/export, /api/catalog/changes en de taxonomie-CSV's.

# 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"

Als source is ingesteld, bevat elk item een veld Source. Encar-id's blijven gewone getallen. Id's van KB Chachacha en K Car hebben een prefix (kbc:..., kcar:...) - geef ze ongewijzigd door aan /api/vehicle/{id}. Met lang=en worden model- en uitvoeringsnamen van alle drie de marktplaatsen in het Engels geretourneerd.

Dealers plaatsen dezelfde auto vaak op Encar en KB Chachacha. Een KB Chachacha-advertentie wordt aan een actieve Encar-advertentie gekoppeld via het Koreaanse kenteken of, als KB Chachacha geen kenteken publiceert, via de maand van eerste registratie, de kilometerstand en de prijs; de koppeling wordt meerdere keren per dag opnieuw berekend, na elke catalogusronde van Encar en KB Chachacha. Gekoppelde KB Chachacha-advertenties worden niet geretourneerd door /api/catalog, /api/catalog/export en de andere catalogus-endpoints, met of zonder source (ook niet met alleen source=kbc), zodat dezelfde auto nooit twee keer verschijnt - als Encar is inbegrepen, komt hij terug als de Encar-advertentie.

In /api/catalog/changes?source=kbc en /api/vehicle/kbc:{id} hebben deze advertenties IsDuplicate: true en DuplicateOf (het ID van de Encar-advertentie, als numerieke string); net als bij Encar-items zijn beide velden alleen aanwezig als ze true zijn. Wanneer de markering wordt gezet of opgeheven, legt de wijzigingsfeed een updated-event vast waarvan changedFields duplicate bevat. Om een lokale kopie consistent te houden met /api/catalog, verwijdert u KB Chachacha-items die binnenkomen met IsDuplicate: true en voegt u ze weer toe zodra een update zonder dat veld binnenkomt.

De wijzigingsfeed accepteert één bron per aanroep (encar, kbc of kcar) en houdt voor elke bron een aparte cursor bij.

Dekking per marktplaats

Niet elke marktplaats publiceert elk veld.

• KB Chachacha publiceert het aantal zitplaatsen voor een deel van zijn advertenties.
• KB Chachacha-detail = het catalogusitem plus het openbare historieblok (ongevalsmarkering, total loss, waterschade, commercieel gebruik, pandrechten, frame- en paneeldiagnose). Elk KB Chachacha-item bevat bovendien InsuranceClaims: het aantal verzekeringsschades dat op de advertentiepagina staat. Het detail bevat ook InspectionReportUrl en InspectionReportType: het keuringsrapport dat KB Chachacha voor de auto toont (link = rapport op de website van het keuringsbedrijf, scan = alleen gescande afbeeldingen op de advertentiepagina, null = nog onbekend). Als InspectionAvailable true is, levert GET /api/inspection/kbc:{id} dat rapport als gestructureerde gegevens in hetzelfde formaat als een Encar-keuringsrapport (master, outers, inners, images), plus een source-blok - bij ongeveer twee op de vijf KB Chachacha-advertenties met een gelinkt keuringsrapport.
• K Car heeft geen aparte rapportdocumenten; aantal ongevallen, verzekeringsuitkeringen en eigenaarswissels zijn onderdeel van het voertuigdetail.

Filteren op een veld dat een marktplaats niet aanbiedt, sluit de voertuigen van die marktplaats uit van de resultaten. Voorbeeld: frame_clean=true met source=all retourneert alleen advertenties van Encar en K Car.

API-eindpunten

Alle beschikbare eindpunten voor toegang tot Koreaanse voertuiggegevens.

Dropdown-gegevens (CSV)

Download de merk-, model- en versielijsten als CSV, cache ze en bouw je dropdowns daaruit op - geen facet-aanroepen per klik en geen offline mapping. Elk bestand bevat een aantalkolom, en het versiebestand bevat de opsplitsing per carrosserie (Coupé / Sedan / Cabrio).

Veelgestelde Vragen