CarDossier Market API

Dane rynku używanych samochodów w Polsce w czasie rzeczywistym — wycena, historia cen, płynność i ceny regionalne. Zasilane przez ponad 2 miliony aktywnych ogłoszeń zbieranych codziennie z głównych polskich serwisów ogłoszeniowych.

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

Uwierzytelnianie

Wszystkie żądania API muszą zawierać klucz API w nagłówku HTTP X-API-Key. Klucz otrzymasz e-mailem 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 w formie zaszyfrowanej. W razie utraty klucza skontaktuj się z pomocą techniczną — możemy go odszukać na podstawie Twojego adresu e-mail.

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.

Kup kredyty na stronie /api/pricing.

Kody błędów

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

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.

Parametry

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 miesięczny trend średnich cen za okres do 24 miesięcy. Przydatne do identyfikacji wzorców sezonowych i krzywych deprecjacji. Koszt: 10 kredytów.

Parametry

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

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

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

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.

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

Gotowy do użycia serwer Model Context Protocol (MCP) umożliwia podłączenie CarDossier API do Claude, Cursor lub dowolnego klienta AI kompatybilnego z MCP. Pobierz skrypt serwera z /api/mcp-server.py i skonfiguruj go swoim kluczem API.

# Zainstaluj zależności
pip install mcp requests

# Ustaw klucz API
export CARDOSSIER_API_KEY="twój_klucz_tutaj"

# Uruchom serwer MCP
python mcp-server.py

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.