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
🇵🇱 Wersja polska

CarDossier Market API

The dataset contains more than 2.4 million historical and recent listing records collected from Otomoto and OLX. This is the cumulative dataset size. The valuation response provides its own sample size and uses asking prices in PLN.

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

Authentication

Try it without a key first: every market endpoint answers 5 keyless demo calls per IP per day with full real data — just omit the header entirely:

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

For more quota, pass your API key in the X-API-Key HTTP header. You get a key by email after the free registration (50 credits, no card) or after purchasing credits.

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

API keys are stored as SHA-256 hashes — we cannot look up a lost key. If you lose yours, contact support and we will issue a new one for your account.

Credits & Pricing

The API uses a prepaid credit system. Each endpoint call deducts a fixed number of credits from your balance. Credits never expire. Your current balance is returned in every API response as data.credits_remaining.

EndpointCredits per call
/v1/market/valuation8
/v1/market/price-history10
/v1/market/liquidity6
/v1/market/valuation-factors12
/v1/market/regional8

Buy credits at /api/pricing.

Error Codes

All errors follow a consistent envelope: {"status":"error","error":{"code":"...","message":"..."}}

HTTP StatuscodeDescription
401UNAUTHORIZEDInvalid or empty X-API-Key header. Omitting the header entirely uses the keyless demo tier instead.
401ACCOUNT_DISABLEDYour account has been disabled.
402INSUFFICIENT_CREDITSNot enough credits. Response includes top_up_url.
400INVALID_PARAMETERMissing or invalid query parameter. The charge is auto-refunded.
404INSUFFICIENT_DATAFewer than 10 matching listings found. The charge is auto-refunded.
429DEMO_LIMIT_REACHEDKeyless demo quota exhausted (5/day per IP). Retry-After header set; response includes register_url.
429RATE_LIMIT_EXCEEDEDToo many requests from this IP (120/min).
500INTERNAL_ERRORServer error. The charge is auto-refunded — please retry.

GET /v1/market/valuation

Returns average, median, P25 and P75 prices for a specific make/model/year combination. Optionally filter by fuel type, gearbox, or mileage range. Costs 8 credits.

Valuation sample methodology

sample_basis: recent_source_filtered means at least 30 eligible comparable listings remained after filtering. Otomoto uses an observation in the last 30 days, or a detail scrape when no census observation exists. OLX-only records use a scrape in the last 45 days. Merged records count once and require a recent Otomoto census observation. A recent scrape is evidence of observation, not a guarantee that the advert is still live.

The recent sample excludes listings marked as disappeared, damaged or new, prices below 500 PLN and non-PLN prices. It also removes prices outside one quarter to four times the comparable median. Seller flags may be missing or inaccurate.

If the recent check cannot supply 30 comparables, sample_basis: historical_listing_pool identifies the existing broader listing sample. It can contain older or delisted adverts and does not use the recent sample's exclusions. The minimum of 10 comparables still applies. recent_sample_size reports how many recent comparables were available, or null when the historical sample itself is too small for the recent threshold or the recent lookup times out. Prices are asking prices, and P25–P75 is the observed interquartile range.

Parameters

ParameterTypeDescription
make requiredstringVehicle manufacturer (e.g. Volkswagen)
model requiredstringVehicle model (e.g. Golf)
year requiredintegerProduction year (e.g. 2019)
fuel_type optionalstringFilter by fuel type. English aliases: petrol, diesel, hybrid, phev, electric, lpg, cng, hydrogen — or Polish values: Benzyna, Diesel, Hybryda, Hybryda Plug-in, Elektryczny, Benzyna+LPG, Benzyna+CNG, Wodór
gearbox optionalstringFilter by gearbox. Values: manual/automatic or Manualna/Automatyczna
mileage optionalintegerTarget mileage in km. Returns listings within ±30% range.

Example Response

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

Returns observed monthly average asking prices. You can request up to 24 months. The trend array contains months with observations. coverage reports the first and last month and the number of returned months. Costs 10 credits.

Parameters

ParameterTypeDescription
make requiredstringVehicle manufacturer
model requiredstringVehicle model
year requiredintegerProduction year
months optionalintegerNumber of months of history (1–24, default: 6)

Example Response

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

Returns estimated days-on-market for a vehicle type — how long it typically takes to sell. Costs 6 credits.

Parameters

ParameterTypeDescription
make requiredstringVehicle manufacturer
model requiredstringVehicle model
year requiredintegerProduction year

Example Response

{
  "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": "Estimated DOM includes a 13-day compensation for initial scraper detection delay.",
    "credits_used": 6,
    "credits_remaining": 976
  }
}

GET /v1/market/valuation-factors

Quantifies the price impact of import status, gearbox type, and fuel type. Returns percentage price differences vs. baseline. Costs 12 credits.

Parameters

ParameterTypeDescription
make requiredstringVehicle manufacturer
model requiredstringVehicle model
year requiredintegerProduction year

Example Response

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

Compares average prices across Polish voivodeships, with percentage deviation from the national average. Costs 8 credits.

Parameters

ParameterTypeDescription
make requiredstringVehicle manufacturer
model requiredstringVehicle model
year requiredintegerProduction year

Example Response

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

Returns your account information. Does not deduct credits.

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

GET /v1/account/usage

Returns your recent transaction history. Does not deduct credits.

ParameterTypeDescription
limit optionalintegerNumber of transactions to return (1–200, default: 50)

OpenAPI 3.1 Schema

The full OpenAPI 3.1 schema is available at https://car-dossier.com/openapi.yaml. Import it into Postman, Insomnia, GPT-4 Actions, or any OpenAPI-compatible tool.

MCP Server

Hosted endpoint https://car-dossier.com/mcp uses Streamable HTTP. Connect without headers for up to 5 demo calls per IP per UTC day. Shared network exits share the quota.

  1. Call get_market_valuation with {"make":"Volkswagen","model":"Golf","year":2019}.
  2. Register for 50 credits, or buy credits with the same email. Configure the X-API-Key HTTP header in your client's secret settings.
  3. Read structuredContent.data on success or structuredContent.error when isError is true. An invalid key returns UNAUTHORIZED.

For a paid retry, reuse the same request_id tool argument or Idempotency-Key header. Use a new value for each new operation. Reusing a value with different inputs returns IDEMPOTENCY_CONFLICT. A replay returns the original balance snapshot.

Clients that cannot set custom HTTP headers can use the local stdio package with CARDOSSIER_API_KEY, or call REST directly. Native OAuth is unavailable on the hosted endpoint.

# Install from PyPI (recommended)
pip install cardossier-mcp-server

# Optional: add your API key for full quota
export CARDOSSIER_API_KEY="your_key_here"

# Run the MCP server
cardossier-mcp

Source code: github.com/Joyall-au/cardossier-mcp-server. Prefer a single file? Download /api/mcp-server.py and run it with pip install 'mcp<2' requests.

llms.txt

A structured capability manifest for LLMs is available at https://car-dossier.com/llms.txt. This file follows the llmstxt.org standard and allows AI systems to understand what this API does without reading full documentation.