Sprawdzamy pojazd
Wyszukujemy pojazd po numerze rejestracyjnym
Identyfikacja VIN i danych pojazdu
Łączymy się z bazami danych
CEPiK, NHTSA, Euro NCAP i inne źródła
Przygotowujemy wstępny raport
Analiza historii, przebiegu i bezpieczeństwa
🇬🇧 English version

CarDossier Market API

Zbiór obejmuje ponad 2,4 mln historycznych i nowszych rekordów ogłoszeń z Otomoto i OLX. To łączna wielkość zbioru. Odpowiedź wyceny podaje liczebność próby i opiera się na cenach ofertowych w PLN.

Bazowy URL: https://car-dossier.com/api

Uwierzytelnianie

Wypróbuj bez klucza: każdy endpoint rynkowy odpowiada na 5 zapytań demo dziennie na IP z pełnymi, prawdziwymi danymi — po prostu pomiń nagłówek:

curl "https://car-dossier.com/api/v1/market/valuation?make=VW&model=Golf&year=2019"

Aby uzyskać większy limit, przekaż klucz API w nagłówku HTTP X-API-Key. Klucz otrzymasz e-mailem po darmowej rejestracji (50 kredytów, bez karty) lub po zakupie kredytów.

curl https://car-dossier.com/api/v1/market/valuation \
  -H "X-API-Key: TWÓJ_KLUCZ_API" \
  -G -d "make=Volkswagen" -d "model=Golf" -d "year=2019"

Klucze API są przechowywane wyłącznie jako skróty SHA-256 — nie możemy odczytać utraconego klucza. W razie utraty skontaktuj się z pomocą techniczną, a wystawimy nowy klucz dla Twojego konta.

Kredyty i cennik

API korzysta z systemu przedpłaconych kredytów. Każde wywołanie endpointu odejmuje określoną liczbę kredytów z Twojego salda. Kredyty nigdy nie wygasają. Aktualne saldo jest zwracane w każdej odpowiedzi API jako data.credits_remaining.

EndpointKredyty za wywołanie
/v1/market/valuation8
/v1/market/price-history10
/v1/market/liquidity6
/v1/market/valuation-factors12
/v1/market/regional8

Kup kredyty na stronie /api/pricing.

Kody błędów

Wszystkie błędy mają spójną strukturę: {"status":"error","error":{"code":"...","message":"..."}}

Status HTTPKodOpis
401UNAUTHORIZEDNieprawidłowy lub pusty nagłówek X-API-Key. Całkowite pominięcie nagłówka uruchamia tryb demo bez klucza.
401ACCOUNT_DISABLEDTwoje konto zostało wyłączone.
402INSUFFICIENT_CREDITSNiewystarczająca liczba kredytów. Odpowiedź zawiera top_up_url.
400INVALID_PARAMETERBrak lub nieprawidłowy parametr zapytania. Opłata jest automatycznie zwracana.
404INSUFFICIENT_DATAZnaleziono mniej niż 10 pasujących ogłoszeń. Opłata jest automatycznie zwracana.
429DEMO_LIMIT_REACHEDWyczerpany dzienny limit demo bez klucza (5/dzień na IP). Nagłówek Retry-After ustawiony; odpowiedź zawiera register_url.
429RATE_LIMIT_EXCEEDEDZbyt wiele żądań z tego adresu IP (120/min).
500INTERNAL_ERRORBłąd serwera. Opłata jest automatycznie zwracana — spróbuj ponownie.

GET /v1/market/valuation

Zwraca średnią, medianę, P25 i P75 cen dla określonej kombinacji marka/model/rok. Opcjonalnie filtruj według rodzaju paliwa, skrzyni biegów lub przebiegu. Koszt: 8 kredytów.

Metodologia doboru ogłoszeń do wyceny

sample_basis: recent_source_filtered oznacza, że po filtrowaniu pozostało co najmniej 30 porównywalnych ogłoszeń. Dla Otomoto bierzemy pod uwagę obserwację z ostatnich 30 dni lub odczyt ogłoszenia, jeśli brak obserwacji z przeglądu serwisu. Dla rekordów tylko z OLX stosujemy odczyt z ostatnich 45 dni. Rekord połączony liczymy raz i wymagamy niedawnej obserwacji z przeglądu Otomoto. Niedawny odczyt potwierdza obserwację, ale nie gwarantuje, że ogłoszenie nadal jest dostępne.

Z nowszej próby wykluczamy ogłoszenia oznaczone jako zniknięte, pojazdy oznaczone jako uszkodzone lub nowe, ceny poniżej 500 PLN i ceny w innych walutach. Usuwamy też ceny poniżej jednej czwartej lub powyżej czterokrotności mediany próby. Oznaczenia sprzedawców mogą być niepełne lub niedokładne.

Jeśli sprawdzenie nowszych danych nie dostarczy 30 ogłoszeń, sample_basis: historical_listing_pool oznacza dotychczasową, szerszą próbę. Może obejmować starsze lub wycofane ogłoszenia i nie stosuje wykluczeń nowszej próby. Nadal wymagamy co najmniej 10 porównywalnych rekordów. recent_sample_size podaje liczebność nowszej próby lub null, gdy szersza próba jest zbyt mała lub sprawdzenie nowszych danych przekroczy limit czasu. Wycena dotyczy cen ofertowych, a P25–P75 to obserwowany przedział międzykwartylowy.

Parametry

ParametrTypOpis
make wymaganystringProducent pojazdu (np. Volkswagen)
model wymaganystringModel pojazdu (np. Golf)
year wymaganyintegerRok produkcji (np. 2019)
fuel_type opcjonalnystringFiltruj według rodzaju paliwa. Aliasy angielskie: petrol, diesel, hybrid, phev, electric, lpg, cng, hydrogen — lub wartości polskie: Benzyna, Diesel, Hybryda, Hybryda Plug-in, Elektryczny, Benzyna+LPG, Benzyna+CNG, Wodór
gearbox opcjonalnystringFiltruj według skrzyni biegów. Wartości: Manualna, Automatyczna
mileage opcjonalnyintegerDocelowy przebieg w km. Zwraca ogłoszenia w zakresie ±30%.

Przykładowa odpowiedź

{
  "status": "success",
  "data": {
    "make": "Volkswagen",
    "model": "Golf",
    "year": 2019,
    "currency": "PLN",
    "filters": { "fuel_type": null, "gearbox": null, "mileage": null },
    "valuation": {
      "average": 78400,
      "median": 76900,
      "p25": 68000,
      "p75": 87500
    },
    "sample_size": 342,
    "credits_used": 8,
    "credits_remaining": 992
  }
}

GET /v1/market/price-history

Zwraca obserwowane średnie miesięczne ceny ofertowe. Możesz zapytać o maksymalnie 24 miesiące. Tablica trend zawiera miesiące, dla których są dane. Pole coverage podaje pierwszy i ostatni miesiąc oraz liczbę zwróconych miesięcy. Koszt: 10 kredytów.

Parametry

ParametrTypOpis
make wymaganystringProducent pojazdu
model wymaganystringModel pojazdu
year wymaganyintegerRok produkcji
months opcjonalnyintegerLiczba miesięcy historii (1–24, domyślnie: 6)

Przykładowa odpowiedź

{
  "status": "success",
  "data": {
    "make": "Volkswagen", "model": "Golf", "year": 2019,
    "currency": "PLN",
    "months_requested": 6,
    "trend": [
      { "month": "2026-01", "avg_price": 76200, "sample_size": 89 },
      { "month": "2026-02", "avg_price": 77100, "sample_size": 94 }
    ],
    "credits_used": 10,
    "credits_remaining": 982
  }
}

GET /v1/market/liquidity

Zwraca szacowany czas sprzedaży pojazdu danego typu — jak długo zazwyczaj trwa znalezienie kupca. Koszt: 6 kredytów.

Parametry

ParametrTypOpis
make wymaganystringProducent pojazdu
model wymaganystringModel pojazdu
year wymaganyintegerRok produkcji

Przykładowa odpowiedź

{
  "status": "success",
  "data": {
    "make": "Volkswagen", "model": "Golf", "year": 2019,
    "estimated_days_on_market": 42,
    "observed_listing_span": 29,
    "active_listings": 342,
    "sample_size": 1204,
    "note": "Szacowany czas sprzedaży uwzględnia 13-dniową korektę na opóźnienie detekcji przez scraper.",
    "credits_used": 6,
    "credits_remaining": 976
  }
}

GET /v1/market/valuation-factors

Określa wpływ na cenę takich czynników jak status importu, rodzaj skrzyni biegów i rodzaj paliwa. Zwraca procentowe różnice cen względem wartości bazowej. Koszt: 12 kredytów.

Parametry

ParametrTypOpis
make wymaganystringProducent pojazdu
model wymaganystringModel pojazdu
year wymaganyintegerRok produkcji

Przykładowa odpowiedź

{
  "status": "success",
  "data": {
    "make": "Volkswagen", "model": "Golf", "year": 2019,
    "currency": "PLN",
    "total_sample_size": 342,
    "factors": [
      {
        "dimension": "gearbox",
        "baseline": { "label": "Manualna", "avg_price": 72000, "sample_size": 180 },
        "comparison": { "label": "Automatyczna", "avg_price": 86400, "sample_size": 162 },
        "price_diff_percent": 20.0
      }
    ],
    "credits_used": 12,
    "credits_remaining": 964
  }
}

GET /v1/market/regional

Porównuje średnie ceny w polskich województwach z procentowym odchyleniem od średniej krajowej. Koszt: 8 kredytów.

Parametry

ParametrTypOpis
make wymaganystringProducent pojazdu
model wymaganystringModel pojazdu
year wymaganyintegerRok produkcji

Przykładowa odpowiedź

{
  "status": "success",
  "data": {
    "make": "Volkswagen", "model": "Golf", "year": 2019,
    "currency": "PLN",
    "national_average": 78400,
    "total_sample_size": 342,
    "regions": [
      { "region": "Mazowieckie", "avg_price": 82100, "sample_size": 68, "vs_national_pct": 4.7 },
      { "region": "Śląskie", "avg_price": 75300, "sample_size": 54, "vs_national_pct": -3.9 }
    ],
    "credits_used": 8,
    "credits_remaining": 956
  }
}

GET /v1/account/me

Zwraca informacje o Twoim koncie. Nie odejmuje kredytów.

curl https://car-dossier.com/api/v1/account/me \
  -H "X-API-Key: TWÓJ_KLUCZ_API"

GET /v1/account/usage

Zwraca historię ostatnich transakcji. Nie odejmuje kredytów.

ParametrTypOpis
limit opcjonalnyintegerLiczba transakcji do zwrócenia (1–200, domyślnie: 50)

Schemat OpenAPI 3.1

Pełny schemat OpenAPI 3.1 jest dostępny pod adresem https://car-dossier.com/openapi.yaml. Zaimportuj go do Postmana, Insomnia, GPT-4 Actions lub dowolnego narzędzia kompatybilnego z OpenAPI.

Serwer MCP

Hostowany endpoint https://car-dossier.com/mcp używa Streamable HTTP. Połącz się bez nagłówków, aby wykonać do 5 zapytań demo na adres IP na dobę UTC. Użytkownicy wspólnego adresu IP dzielą limit.

  1. Wywołaj get_market_valuation z parametrami {"make":"Volkswagen","model":"Golf","year":2019}.
  2. Zarejestruj się, aby dostać 50 kredytów, lub kup kredyty na ten sam e-mail. Ustaw nagłówek HTTP X-API-Key w ustawieniach sekretów klienta.
  3. Odczytaj structuredContent.data przy powodzeniu lub structuredContent.error, gdy isError ma wartość true. Nieprawidłowy klucz zwraca UNAUTHORIZED.

Przy ponowieniu płatnego wywołania użyj tego samego argumentu request_id lub nagłówka Idempotency-Key. Dla nowej operacji użyj nowej wartości. Zmiana parametrów przy tym samym kluczu zwraca IDEMPOTENCY_CONFLICT. Ponowienie zwraca saldo zapisane przy pierwotnej operacji.

Jeśli klient nie obsługuje własnych nagłówków HTTP, użyj lokalnego pakietu stdio z CARDOSSIER_API_KEY lub wywołaj REST. Hostowany endpoint nie obsługuje natywnego OAuth.

# Instalacja z PyPI (zalecane)
pip install cardossier-mcp-server

# Opcjonalnie: dodaj klucz API dla pełnego limitu
export CARDOSSIER_API_KEY="twój_klucz_tutaj"

# Uruchom serwer MCP
cardossier-mcp

Kod źródłowy: github.com/Joyall-au/cardossier-mcp-server. Wolisz pojedynczy plik? Pobierz /api/mcp-server.py i uruchom z pip install 'mcp<2' requests.

llms.txt

Ustrukturyzowany manifest możliwości dla modeli językowych jest dostępny pod adresem https://car-dossier.com/llms.txt. Plik ten jest zgodny ze standardem llmstxt.org i pozwala systemom AI zrozumieć działanie tego API bez konieczności czytania pełnej dokumentacji.