CarDossier Market API

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

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

Authentication

All API requests must include your API key in the X-API-Key HTTP header. You receive your key by email 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 hashed server-side. If you lose your key, contact support — we can look it up by your email.

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 is available for connecting CarDossier API to Claude, Cursor, or any MCP-compatible AI client. Download the server script from /api/mcp-server.py and configure it with your API key.

# Install dependencies
pip install mcp requests

# Set your API key
export CARDOSSIER_API_KEY="your_key_here"

# Run the MCP server
python mcp-server.py

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.