CarDossier Market API

Real-time Polish used car market data — valuation, price history, liquidity, and regional pricing. Powered by over 1.4 million active listings scraped daily from major Polish marketplaces.

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.

Buy credits at /api/pricing.

Error Codes

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

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.

Parameters

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 monthly average price trend for up to 24 months. Useful for identifying seasonal patterns and depreciation curves. Costs 10 credits.

Parameters

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

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

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

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.

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

A ready-to-use Model Context Protocol (MCP) server connects CarDossier to Claude, Cursor, Windsurf, or any MCP-compatible AI client. It works out of the box with no API key — the keyless demo tier serves 5 real calls per day; add a free key (50 credits, no card) for more.

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