Dokumentacja

Bazowy URL

Wszystkie zapytania API kierowane są pod następujący bazowy URL:

https://api.encarapi.com

Na przykład, aby pobrać oferty:

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

Uwierzytelnianie

Uwierzytelniaj swoje zapytania za pomocą klucza API. Przekaż go jako parametr zapytania lub przez nagłówek 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-dniowy okres próbny

Przetestuj API przez 5 dni ze wszystkimi trzema platformami (Encar, KB Chachacha, K Car), w tym synchronizację zmian (ostatnie 7 dni), pobieranie zbiorcze (1 000 id dziennie) i podgląd archiwum (100 usuniętych ogłoszeń dziennie). 100 000 wierszy katalogu i 2 000 zapytań o szczegóły łącznie (maks. 1 000 dziennie). Pliki referencyjne do pobrania (CSV) są częścią płatnych planów. Pełny eksport katalogu jest dostępny od planu Business. Po okresie próbnym subskrypcja jest kontynuowana w planie Starter za 149 €/miesiąc - możesz zrezygnować w dowolnym momencie przed 5. dniem.

Wartości po rosyjsku (lang=ru)

Każdy endpoint, który przyjmuje lang=en, przyjmuje też lang=ru: wartości wyświetlane przychodzą po rosyjsku, a cała reszta pozostaje bez zmian (id, kody, ceny, liczby, nazwy pól). Wartość bez rosyjskiej etykiety wraca do angielskiej. Rosyjskie etykiety mogą być z czasem dopracowywane, dlatego łącz dane po id i kodach, a nie po etykietach.

• Tłumaczone: paliwo, skrzynia biegów, napęd, kolor nadwozia i wnętrza, klasa nadwozia, typ sprzedaży, nazwy regionów i miast, nazwy opcji oraz ogólne słowa w nazwach wersji (Diesel -> дизель, 7-Seater -> 7 мест). Generacje modeli: Carnival 4 Gen -> Carnival 4 поколение. Nazwy marek, modeli i wersji pozostają w alfabecie łacińskim, jak na rosyjskich portalach motoryzacyjnych.
• Filtry przyjmują także wartości rosyjskie: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. Wartości angielskie nadal działają.
• /api/enums?lang=ru dodaje nameRu do każdej wartości i wypisuje wartości drivetrain i sell_type. /api/nav?lang=ru zwraca rosyjski DisplayValue; Value pozostaje angielskim kodem do filtrowania. Pliki CSV referencyjne z lang=ru dostają rosyjską nazwę jako dodatkową kolumnę po ostatniej.
• /api/vehicle/{id}?lang=ru i endpoint bulk zwracają po rosyjsku wartości spec z Encar, nazwy category i nazwy optionsDecoded, a ogłoszenia KB Chachacha tak jak w katalogu.
• /api/catalog/export?lang=ru to ten sam plik z kolumnami etykiet po rosyjsku; kolejność kolumn i wszystkie pozostałe kolumny bez zmian.
• Nie są tłumaczone: raporty z przeglądu, historia ubezpieczeniowa, diagnozy Encar, historie pojazdów Encar, dane szczegółowe K Car, pakiety opcji Encar (wolny tekst z ogłoszenia) oraz endpointy ciężarówek i koparek (przy lang=ru odpowiadają po angielsku).

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

Wartości po niemiecku (lang=de)

lang=de działa jak lang=ru: wartości wyświetlane przychodzą po niemiecku, a cała reszta pozostaje bez zmian (id, kody, ceny, liczby, nazwy pól). Wartość bez niemieckiej etykiety wraca do angielskiej.

• Tłumaczone: paliwo, skrzynia biegów, napęd, kolory, klasa nadwozia, typ sprzedaży, nazwy opcji oraz nazwy modeli i wersji z naszych niemieckich tabel (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). Regiony mają nazwy angielskie, miasta pozostają po angielsku.
• Filtry przyjmują także wartości niemieckie: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. Niemieckie nazwy modeli mogą łączyć liftingi: Carnival 4. Generation obejmuje Carnival 4 Gen i The New Carnival 4 Gen.
• Listy, szczegóły, bulk i eksport działają jak przy lang=ru: nameDe w /api/enums i /api/taxonomy/option-packages, niemiecki DisplayValue w /api/nav, kolumny *_de w plikach CSV referencyjnych, catalog_export_de.csv dla eksportu. Nie jest tłumaczone to samo co przy 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"

Trzy platformy, jedno API

API udostępnia aktualne ogłoszenia z trzech największych koreańskich platform z samochodami używanymi. Każdy endpoint domyślnie zwraca Encar, więc istniejące integracje działają bez zmian. Dwie pozostałe włącza się parametrem source.

Wybór źródeł

source jest akceptowany przez /api/catalog, /api/nav, /api/enums, /api/model-search, /api/catalog/export, /api/catalog/changes oraz pliki CSV taksonomii.

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

Gdy ustawiono source, każdy element zawiera pole Source. Identyfikatory Encar pozostają zwykłymi liczbami. Identyfikatory KB Chachacha i K Car mają prefiks (kbc:..., kcar:...) - przekazuj je bez zmian do /api/vehicle/{id}. Przy lang=en nazwy modeli i wersji ze wszystkich trzech platform są zwracane po angielsku.

Dealerzy często wystawiają ten sam samochód na Encar i KB Chachacha. Ogłoszenie KB Chachacha jest dopasowywane do aktywnego ogłoszenia Encar po koreańskim numerze rejestracyjnym, a gdy KB Chachacha nie publikuje numeru - po miesiącu pierwszej rejestracji, przebiegu i cenie; dopasowanie jest przeliczane kilka razy dziennie, po każdym przebiegu katalogu Encar i KB Chachacha. Dopasowanych ogłoszeń KB Chachacha nie zwracają /api/catalog, /api/catalog/export ani inne endpointy katalogu, z source lub bez (również nie przy samym source=kbc), więc ten sam samochód nigdy nie pojawia się dwa razy - jeśli Encar jest uwzględniony, zwracany jest jako ogłoszenie Encar.

W /api/catalog/changes?source=kbc i /api/vehicle/kbc:{id} takie ogłoszenia mają IsDuplicate: true i DuplicateOf (identyfikator ogłoszenia Encar jako ciąg liczbowy); tak jak w elementach Encar oba pola występują tylko wtedy, gdy mają wartość true. Gdy oznaczenie zostaje ustawione lub usunięte, feed zmian zapisuje zdarzenie updated, którego changedFields zawiera duplicate. Aby lokalna kopia była spójna z /api/catalog, usuwaj elementy KB Chachacha, które przychodzą z IsDuplicate: true, i dodawaj je ponownie, gdy przyjdzie aktualizacja bez tego pola.

Feed zmian przyjmuje jedno źródło na wywołanie (encar, kbc lub kcar) i dla każdego utrzymuje osobny kursor.

Zakres danych według platformy

Nie każda platforma publikuje każde pole.

• KB Chachacha publikuje liczbę miejsc dla części swoich ogłoszeń.
• Szczegóły KB Chachacha = element katalogu plus publiczny blok historii (flaga wypadku, szkoda całkowita, zalanie, użytek komercyjny, zastawy, diagnostyka ramy i paneli nadwozia). Każdy element KB Chachacha zawiera też InsuranceClaims: liczbę szkód ubezpieczeniowych widoczną na stronie ogłoszenia. Szczegóły zawierają też InspectionReportUrl i InspectionReportType: raport z inspekcji, który KB Chachacha pokazuje dla samochodu (link = raport na stronie firmy inspekcyjnej, scan = tylko zeskanowane obrazy na stronie ogłoszenia, null = jeszcze nieznany). Gdy InspectionAvailable ma wartość true, GET /api/inspection/kbc:{id} zwraca ten raport jako dane strukturalne w tym samym formacie co raport z inspekcji Encar (master, outers, inners, images) wraz z blokiem source - dotyczy to mniej więcej dwóch na pięć ogłoszeń KB Chachacha z podlinkowanym raportem.
• K Car nie ma osobnych dokumentów raportów; liczba wypadków, wypłaty z ubezpieczenia i zmiany właściciela są częścią szczegółów pojazdu.

Filtrowanie po polu, którego dana platforma nie udostępnia, wyklucza jej pojazdy z wyników. Przykład: frame_clean=true z source=all zwraca wyłącznie ogłoszenia Encar i K Car.

Endpointy API

Wszystkie dostępne endpointy do uzyskiwania danych koreańskich pojazdów.

Dane list rozwijanych (CSV)

Pobierz listy marek, modeli i badge jako CSV, zapisz je w pamięci podręcznej i zbuduj z nich swoje listy rozwijane - żadnych zapytań facetowych przy każdym kliknięciu i żadnego mapowania offline. Każdy plik zawiera kolumnę z liczbą, a plik badge niesie podział według typu nadwozia (Coupe / Sedan / Kabriolet).

Najczęściej zadawane pytania