Dokumentace

Základní URL

Všechny požadavky na API směřují na následující základní URL:

https://api.encarapi.com

Například pro získání nabídek:

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

Autentizace

Ověřujte své požadavky pomocí API klíče. Předejte ho jako parametr dotazu nebo přes hlavičku 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

5denní zkušební verze

Vyzkoušejte API na 5 dní se všemi třemi tržišti (Encar, KB Chachacha, K Car), včetně synchronizace změn (posledních 7 dní), hromadných dotazů (1 000 id denně) a náhledu archivu (100 odstraněných inzerátů denně). 100 000 řádků katalogu a 2 000 dotazů na detail celkem (max. 1 000 denně). Referenční soubory ke stažení (CSV) jsou součástí placených plánů. Kompletní export katalogu je k dispozici od plánu Business. Po zkušebním období vaše předplatné pokračuje v plánu Starter za 149 €/měsíc - kdykoli před 5. dnem můžete zrušit.

Ruské hodnoty (lang=ru)

Každý endpoint, který přijímá lang=en, přijímá také lang=ru: zobrazované hodnoty přicházejí rusky, vše ostatní zůstává stejné (id, kódy, ceny, čísla, názvy polí). Hodnota bez ruského názvu se vrací anglicky. Ruské názvy se mohou časem zpřesňovat, proto propojujte data podle id a kódů, ne podle názvů.

• Překládá se: palivo, převodovka, pohon, barva karoserie a interiéru, třída karoserie, typ prodeje, názvy regionů a měst, názvy výbavy a obecná slova v názvech provedení (Diesel -> дизель, 7-Seater -> 7 мест). Generace modelů: Carnival 4 Gen -> Carnival 4 поколение. Názvy značek, modelů a provedení zůstávají v latince, jako na ruských autobazarech.
• Filtry přijímají i ruské hodnoty: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. Anglické hodnoty dál fungují.
• /api/enums?lang=ru přidá ke každé hodnotě nameRu a vypíše hodnoty drivetrain a sell_type. /api/nav?lang=ru vrací ruský DisplayValue; Value zůstává anglickým kódem pro filtrování. Referenční CSV s lang=ru dostanou ruský název jako další sloupec za posledním.
• /api/vehicle/{id}?lang=ru a bulk endpoint vracejí rusky hodnoty spec z Encaru, názvy category a názvy optionsDecoded, inzeráty KB Chachacha stejně jako v katalogu.
• /api/catalog/export?lang=ru je stejný soubor se sloupci názvů v ruštině; pořadí sloupců a všechny ostatní sloupce se nemění.
• Nepřekládá se: protokoly z prohlídky, pojistná historie, diagnostiky Encar, historie vozidel Encar, detailní data K Car, balíčky výbavy Encar (volný text z inzerátu) a endpointy nákladních vozidel a bagrů (při lang=ru odpovídají anglicky).

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

Německé hodnoty (lang=de)

lang=de funguje jako lang=ru: zobrazované hodnoty přicházejí německy, vše ostatní zůstává stejné (id, kódy, ceny, čísla, názvy polí). Hodnota bez německého názvu se vrací anglicky.

• Překládá se: palivo, převodovka, pohon, barvy, třída karoserie, typ prodeje, názvy výbavy a názvy modelů a provedení z našich německých tabulek (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). Regiony mají anglické názvy, města zůstávají anglicky.
• Filtry přijímají i německé hodnoty: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. Německé názvy modelů mohou spojovat faceliftované verze: Carnival 4. Generation zahrnuje Carnival 4 Gen i The New Carnival 4 Gen.
• Seznamy, detail, bulk a export fungují jako u lang=ru: nameDe v /api/enums a /api/taxonomy/option-packages, německý DisplayValue v /api/nav, sloupce *_de v referenčních CSV, catalog_export_de.csv pro export. Nepřekládá se totéž co u 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"

Tři tržiště, jedno API

API poskytuje aktuální inzeráty ze tří hlavních korejských tržišť s ojetými vozy. Každý koncový bod vrací ve výchozím nastavení Encar, takže stávající integrace fungují beze změny. Zbylá dvě se zapínají parametrem source.

Výběr zdrojů

source přijímají /api/catalog, /api/nav, /api/enums, /api/model-search, /api/catalog/export, /api/catalog/changes a CSV soubory taxonomie.

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

Je-li nastaven source, každá položka obsahuje pole Source. ID z Encar zůstávají prostými čísly. ID z KB Chachacha a K Car mají prefix (kbc:..., kcar:...) - předávejte je beze změny do /api/vehicle/{id}. S lang=en se názvy modelů a výbav ze všech tří tržišť vracejí v angličtině.

Prodejci často inzerují stejný vůz na Encar i KB Chachacha. Inzerát z KB Chachacha se přiřadí k aktivnímu inzerátu na Encar podle korejské SPZ, a pokud ji KB Chachacha nezveřejňuje, podle měsíce první registrace, nájezdu a ceny; přiřazení se přepočítává několikrát denně, po každém průchodu katalogem Encar a KB Chachacha. Přiřazené inzeráty z KB Chachacha nevracejí /api/catalog, /api/catalog/export ani ostatní katalogové endpointy, se source i bez něj (ani se samotným source=kbc), takže se stejný vůz nikdy neobjeví dvakrát - pokud je zahrnut Encar, vrátí se jako inzerát Encar.

V /api/catalog/changes?source=kbc a /api/vehicle/kbc:{id} nesou tyto inzeráty IsDuplicate: true a DuplicateOf (ID inzerátu na Encar jako číselný řetězec); stejně jako u položek Encar jsou obě pole přítomna jen tehdy, když platí true. Když se příznak nastaví nebo zruší, feed změn zapíše událost updated, jejíž changedFields obsahuje duplicate. Aby lokální kopie odpovídala /api/catalog, odstraňte položky KB Chachacha, které přijdou s IsDuplicate: true, a znovu je přidejte, jakmile přijde aktualizace bez tohoto pole.

Feed změn přijímá jeden zdroj na volání (encar, kbc nebo kcar) a pro každý udržuje samostatný kurzor.

Pokrytí podle tržiště

Ne každé tržiště zveřejňuje každé pole.

• KB Chachacha zveřejňuje počet sedadel u části svých inzerátů.
• Detail KB Chachacha = položka katalogu plus veřejný blok historie (příznak nehody, totální škoda, zaplavení, komerční využití, zástavní práva, diagnostika rámu a karosářských dílů). Každá položka KB Chachacha navíc obsahuje InsuranceClaims: počet pojistných událostí uvedený na stránce inzerátu. Detail obsahuje také InspectionReportUrl a InspectionReportType: inspekční protokol, který KB Chachacha k autu zobrazuje (link = protokol na webu inspekční firmy, scan = jen naskenované obrázky na stránce inzerátu, null = zatím neznámý). Pokud je InspectionAvailable true, vrací GET /api/inspection/kbc:{id} tento protokol jako strukturovaná data ve stejném formátu jako inspekční zpráva z Encaru (master, outers, inners, images) spolu s blokem source - zhruba u dvou z pěti inzerátů KB Chachacha s odkazem na protokol.
• K Car nemá samostatné dokumenty zpráv; počty nehod, pojistná plnění a změny vlastníka jsou součástí detailu vozidla.

Filtrování podle pole, které tržiště neposkytuje, vyřadí vozidla tohoto tržiště z výsledků. Příklad: frame_clean=true se source=all vrátí pouze inzeráty z Encar a K Car.

Koncové body API

Všechny dostupné koncové body pro přístup k datům korejských vozidel.

Data pro rozbalovací nabídky (CSV)

Stáhněte seznamy značek, modelů a badge jako CSV, uložte je do cache a sestavte z nich své rozbalovací nabídky - žádné facetové dotazy při každém kliknutí a žádné offline mapování. Každý soubor obsahuje sloupec s počtem a soubor badge nese rozdělení podle typu karoserie (Coupe / Sedan / Kabriolet).

Často kladené otázky