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.
| Endpoint | Credits per call |
|---|---|
| /v1/market/valuation | 8 |
| /v1/market/price-history | 10 |
| /v1/market/liquidity | 6 |
| /v1/market/valuation-factors | 12 |
| /v1/market/regional | 8 |
Buy credits at /api/pricing.
Error Codes
All errors follow a consistent envelope: {"status":"error","error":{"code":"...","message":"..."}}
| HTTP Status | code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Invalid or empty X-API-Key header. Omitting the header entirely uses the keyless demo tier instead. |
| 401 | ACCOUNT_DISABLED | Your account has been disabled. |
| 402 | INSUFFICIENT_CREDITS | Not enough credits. Response includes top_up_url. |
| 400 | INVALID_PARAMETER | Missing or invalid query parameter. The charge is auto-refunded. |
| 404 | INSUFFICIENT_DATA | Fewer than 10 matching listings found. The charge is auto-refunded. |
| 429 | DEMO_LIMIT_REACHED | Keyless demo quota exhausted (5/day per IP). Retry-After header set; response includes register_url. |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests from this IP (120/min). |
| 500 | INTERNAL_ERROR | Server 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
| Parameter | Type | Description |
|---|---|---|
| make required | string | Vehicle manufacturer (e.g. Volkswagen) |
| model required | string | Vehicle model (e.g. Golf) |
| year required | integer | Production year (e.g. 2019) |
| fuel_type optional | string | Filter 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 optional | string | Filter by gearbox. Values: manual/automatic or Manualna/Automatyczna |
| mileage optional | integer | Target 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
| Parameter | Type | Description |
|---|---|---|
| make required | string | Vehicle manufacturer |
| model required | string | Vehicle model |
| year required | integer | Production year |
| months optional | integer | Number 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
| Parameter | Type | Description |
|---|---|---|
| make required | string | Vehicle manufacturer |
| model required | string | Vehicle model |
| year required | integer | Production 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
| Parameter | Type | Description |
|---|---|---|
| make required | string | Vehicle manufacturer |
| model required | string | Vehicle model |
| year required | integer | Production 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
| Parameter | Type | Description |
|---|---|---|
| make required | string | Vehicle manufacturer |
| model required | string | Vehicle model |
| year required | integer | Production 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.
| Parameter | Type | Description |
|---|---|---|
| limit optional | integer | Number 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.
- Call
get_market_valuationwith{"make":"Volkswagen","model":"Golf","year":2019}. - Register for 50 credits, or buy credits with the same email. Configure the
X-API-KeyHTTP header in your client's secret settings. - Read
structuredContent.dataon success orstructuredContent.errorwhenisErroris true. An invalid key returnsUNAUTHORIZED.
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.