GET /v1/market-price

Market price estimate (p25 / median / p75) from listings

Statistics over comparable asking prices in the platform listings cache (last 90 days): same make/model, year ±1, optional fuel and mileage, deduplicated by VIN, IQR outliers removed. sample_size 0 means no data (p25/median/p75 are null). Requires scope read:pricing.

Authentication: header Authorization: Bearer rv_live_... (API keys and scopes)
Required scope: read:pricing

Descriptions of the operation, parameters and fields come from the OpenAPI specification (openapi.json).

Parameters

Field	In	Type	Required	Description
`make`	query	`string`	yes	Make, e.g. "Toyota" or "BMW" (case-insensitive).
`model`	query	`string`	yes	Model, e.g. "Camry" or "X5".
`year`	query	`integer`	yes	Model year. Comparable listings are taken within ±1 year.
`market`	query	`"ua" \| "pl"`	yes	Market whose asking prices are used: ua (Ukraine) or pl (Poland).
`fuel`	query	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other"`	no	Restrict comparables to this fuel type.
`mileage_km`	query	`number \| null`	no	Mileage in km; comparables are taken within ±35% (min ±30 000 km).
`currency`	query	`string`	no	ISO-4217 currency of the result (default EUR). Converted with the current FX rate.

Responses

200

Market price estimate.

application/json · Schema: MarketPriceResponse

Field	Type	Required	Description
`market`	`"ua" \| "pl"`	yes
`currency`	`string`	yes
`p25`	`number \| null`	yes
`median`	`number \| null`	yes
`p75`	`number \| null`	yes
`sample_size`	`integer`	yes
`sources`	`object[]`	yes
`sources[].sourceKey`	`string`	no
`sources[].count`	`integer`	no
`confidence`	`number`	yes
`confidence_level`	`"none" \| "low" \| "medium" \| "high"`	yes
`filters`	`object`	yes
`filters.yearFrom`	`number`	yes
`filters.yearTo`	`number`	yes
`filters.fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other" \| null`	yes
`filters.mileageKm`	`array \| null`	yes
`excluded`	`object`	yes
`excluded.outliers`	`integer`	yes
`excluded.notComparablePrice`	`integer`	yes
`vehicle`	`object`	yes
`vehicle.make`	`string`	yes
`vehicle.model`	`string`	yes
`vehicle.year`	`integer`	yes
`vehicle.fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other" \| null`	yes
`vehicle.mileage_km`	`number \| null`	yes
`model_match`	`"exact" \| "base_model"`	yes	exact: comparables have the same model; base_model: no exact matches, so the base model (first word, e.g. "CAMRY SE" → "CAMRY") and its trims were used - a rougher estimate.
`matched_model`	`string`	yes	Model the sample was actually computed for.
`as_of`	`string (date-time)`	yes	When the estimate was computed.
`fx_rate_eur`	`number \| null`	yes	1 EUR in the result currency; null if the currency is EUR.
`note`	`string`	yes	How to read the numbers (asking prices from listings_cache, not transaction prices).
`basis`	`"listings_cache" \| "catalog_index"`	no	Which sample produced p25/median/p75: listings_cache (market listings seen by Scout) or catalog_index (EU catalog index; the larger sample wins).
`catalog`	`object`	no	EU catalog comparables (null — catalog unavailable).
`catalog.count`	`integer`	no	Similar active EU listings in the catalog index.
`catalog.sample_size`	`integer`	no
`catalog.median`	`number \| null`	no
`catalog.p25`	`number \| null`	no
`catalog.p75`	`number \| null`	no
`catalog.currency`	`string`	no
`catalog.basis`	`"landed_no_delivery" \| "listing_price"`	no	ua: median turnkey (price + Ukrainian taxes, delivery NOT included); pl: median listing price.
`catalog.scope`	`"country" \| "eu"`	no