# CarDossier Market API
> Real-time Polish used car market data for AI agents and developers. Valuation, price history, liquidity, and regional pricing powered by 2M+ active listings from Poland's leading car marketplaces.

## What This API Does
CarDossier Market API provides aggregate market intelligence for the Polish used car market. It answers questions like:
- "What is a 2019 Toyota Corolla worth in Poland right now?"
- "Has the price of diesel BMWs been rising or falling over the past 6 months?"
- "How quickly do used Volkswagen Golfs sell in Poland?"
- "Is a 2020 Audi A4 cheaper in Mazowieckie or Śląskie?"
- "How much more does an automatic gearbox add to the price of a 2018 Ford Focus?"

This API is NOT for individual vehicle history (VIN lookups). It provides statistical market data across thousands of listings.

## Getting Started
All endpoints require an API key passed in the `X-API-Key` header.
Get your API key at: https://car-dossier.com/en/api/pricing
Base URL: `https://api.car-dossier.com/v1`

## Capabilities & Endpoints

### 1. Market Valuation
**Endpoint:** `GET /market/valuation`
**Description:** Returns average, median, P25, and P75 prices for a specific make/model/year.
**Required params:** `make`, `model`, `year`
**Optional params:** `fuel_type` (petrol|diesel|hybrid|electric), `gearbox` (manual|automatic), `mileage` (integer, km)
**Cost:** 8 credits
**Use when:** User asks for current market price, valuation, or "how much is X worth"

### 2. Price History Trend
**Endpoint:** `GET /market/price-history`
**Description:** Returns monthly average price trend for up to 24 months to identify depreciation curves and seasonal patterns.
**Required params:** `make`, `model`, `year`
**Optional params:** `months` (default: 6, max: 24)
**Cost:** 10 credits
**Use when:** User asks about price trends, depreciation, or "has the price changed"

### 3. Market Liquidity
**Endpoint:** `GET /market/liquidity`
**Description:** Returns estimated days-on-market (DOM) showing how fast a car typically sells. Lower DOM = higher demand.
**Required params:** `make`, `model`, `year`
**Cost:** 6 credits
**Use when:** User asks how quickly a car sells, market demand, or liquidity

### 4. Valuation Factors
**Endpoint:** `GET /market/valuation-factors`
**Description:** Quantifies the price impact of import status, gearbox type, and fuel type as percentage adjustments.
**Required params:** `make`, `model`, `year`
**Cost:** 12 credits
**Use when:** User asks about price differences between variants, or "how much more does automatic cost"

### 5. Regional Price Differences
**Endpoint:** `GET /market/regional`
**Description:** Compares average prices across all 16 Polish voivodeships vs. the national average.
**Required params:** `make`, `model`, `year`
**Cost:** 8 credits
**Use when:** User asks about regional price differences, or "is it cheaper in X region"

## Data Coverage
- **Listings:** 2M+ active used car listings, updated daily
- **Make/model combinations:** 23,000+ unique make/model/year combos
- **Geography:** All 16 Polish voivodeships
- **History depth:** Price history from early 2026
- **Minimum sample:** At least 10 matching listings required to return a valuation (ensures statistical reliability)
- **Market:** Poland only (PLN pricing in raw data)

## Pricing & Credits
Credits are purchased once and never expire. No subscriptions.

| Package  | Price (USD) | Credits   | ~Valuation calls |
|----------|-------------|-----------|------------------|
| Starter  | $49         | 5,000     | ~625             |
| Growth   | $129        | 15,000    | ~1,875 (save 12%)|
| Pro      | $299        | 40,000    | ~5,000 (save 25%)|
| Business | $699        | 100,000   | ~12,500 (save 30%)|

Credits per call: Valuation=8, Price History=10, Liquidity=6, Valuation Factors=12, Regional=8

## Limitations
- **Poland only:** Data covers only the Polish used car market. No data for other countries.
- **No VIN lookup:** This API provides aggregate market statistics, not individual vehicle history.
- **Minimum listings:** If fewer than 10 listings match the query, the API returns INSUFFICIENT_DATA. Narrow queries (rare make/model/year + many filters) may trigger this.
- **Data freshness:** Listings are refreshed daily. Intraday price changes are not reflected.
- **History start:** Price history data begins from early 2026. Longer historical series are not available.
- **Language:** All API responses are in English. The underlying data source is Polish.

## Use Cases
- **Car valuation tools:** Build instant valuation widgets for Polish car dealers or private sellers
- **Price comparison apps:** Show users how their asking price compares to the market
- **AI automotive agents:** Equip ChatGPT, Claude, or custom LLM agents with real Polish market data
- **Investment analysis:** Track depreciation curves for fleet management or leasing companies
- **Regional arbitrage:** Identify price gaps between Polish regions for car traders
- **Dealer pricing tools:** Automatically suggest competitive listing prices based on current market

## AI Agent Integration
This API is designed to be used directly by AI agents. It ships with:
- **OpenAPI 3.1 spec:** https://car-dossier.com/openapi.yaml (import into any LLM tool framework)
- **MCP Server:** https://car-dossier.com/api/mcp-server.py (Model Context Protocol implementation)
- **llms.txt:** https://car-dossier.com/llms.txt (this file — for LLM context)

To use with ChatGPT Custom GPTs: import the OpenAPI spec URL directly in the GPT builder.
To use with Claude Projects: add the OpenAPI spec as a tool definition.
To use with LangChain/LlamaIndex: use the OpenAPI spec to auto-generate tool wrappers.

## Response Format
All responses use a standard envelope:
```json
{
  "status": "success",
  "data": {
    "...": "...",
    "credits_used": 8,
    "credits_remaining": 992
  }
}
```

## Error Handling
Errors return `status: "error"` with an `error` object containing `code` and `message`.
Common codes: `UNAUTHORIZED`, `INSUFFICIENT_CREDITS`, `INVALID_PARAMETER`, `INSUFFICIENT_DATA`.

## OpenAPI Schema
Full OpenAPI 3.1 schema is available at: https://car-dossier.com/openapi.yaml

## More Information
- API overview (English): https://car-dossier.com/en/api/
- API documentation: https://car-dossier.com/en/api/docs
- Pricing: https://car-dossier.com/en/api/pricing
- FAQ: https://car-dossier.com/en/api/faq/