For developers
Vehicle Analytics API
CarRadar tells you what a car is worth on the market today. You describe a car in JSON, we compare it with similar cars for sale in the same country, and we send back a price range and how fast such cars sell.
| Price one car | Price many cars | |
|---|---|---|
| For | A listing form, a quick check | A stock list |
| You get | A suggested price with a low and a high | Full market analytics for each car |
| How | One call, the answer comes straight back | Send up to 50 cars, then read the results |
| Route | POST /vehicle-api/price-suggestion | POST /vehicle-api/jobs |
Getting a key
API keys are issued by hand, one per customer. Write to [email protected] with what you plan to price, roughly how many cars per month, and which countries. We reply with your price per request and create the key.
How you get the key. We write to you when it is ready. Sign in at carradar.app with the same email, open your Account page and press Show my key on the API card. The key is shown once, so copy it right away and keep it on your server, not in a browser or an app. If you lose it, we issue a new one. Send it as Authorization: Bearer your key.
Want to try it first? Ask for a sandbox key. It is free, uses real market data and works on the price endpoint only. It allows 500 requests a month and 1000 in total, and expires after 3 months. Your Account page shows what is left. Going live is a key swap, nothing else changes.
You do not need a paid CarRadar plan to use the API. Your monthly usage also appears in Account > Wallet.
Base URL and authentication
https://carradar.app/api/v1
Every request carries your key as a bearer token. Nothing else is needed.
Authorization: Bearer crk_live_...
Price one car
We compare your car with cars listed in the same country in the last 30 days. You get the answer in the same call. We never return links to listings.
curl -X POST https://carradar.app/api/v1/vehicle-api/price-suggestion \
-H "Authorization: Bearer crk_live_..." \
-H "Content-Type: application/json" \
-d '{
"market": "RS",
"brand": "Volkswagen",
"model": "Tiguan",
"year": 2018,
"mileage": 140000,
"engine": "2.0",
"fuel": "diesel",
"price": 19900
}'{
"statusCode": 200,
"data": {
"environment": "live",
"status": "ok",
"price": { "suggested": 18700, "low": 17795, "high": 21990, "currency": "EUR" },
"confidence": "high",
"comparables": { "count": 19, "windowDays": 30 },
"timeOnMarket": {
"medianDays": 44,
"p25Days": 14,
"p75Days": 100,
"sampleSize": 60,
"completed": 40,
"unfinishedSharePct": 33
},
"comparableLines": {
"lines": [{ "line": "R-Line", "count": 5, "medianPrice": 21990 }],
"unknown": { "count": 14, "medianPrice": 17994 },
"otherLinesCount": 0
},
"filters": {
"yearRange": [2018, 2018],
"mileageRange": [125000, 175000],
"matchedOn": [],
"droppedWords": [],
"equipmentLineMissing": false,
"engine": "2.0",
"fuel": "diesel"
},
"vsMarket": { "askingPrice": 19900, "deltaPct": 6.4, "deltaEur": 1200 }
}
}Read it like this: cars like this one are listed around 18,700 EUR. Half of them sit between 17,795 and 21,990 EUR. We found 19 cars, so confidence is high. Half of such cars are gone within 44 days. 5 of them are R-Line and cost about 21,990 EUR, and 14 do not name a trim. Your asking price of 19,900 EUR is 1,200 EUR (6.4 percent) above the market. The numbers change every day.
What you send
The more you send, the more exact the price. Fields marked must are always needed.
| field | need | what to put |
|---|---|---|
market | must | Country: RS, BA, HR, SI, DE, CH or NLBE. Ask your user, do not guess. |
brand | must | The maker, e.g. "Volkswagen". "VW" also works. |
model | must | The model name only, e.g. "Golf". |
year | must | Model year. Or send yearFrom and yearTo. |
mileage | must | Kilometres. Or send mileageMin and mileageMax. |
engine | should | Engine size in cc or litres, e.g. "1968" or "2.0". Not for electric cars. |
fuel | should | "petrol", "diesel", "hybrid" or "electric". |
transmission | should | "manual" or "automatic". |
equipmentLine | nice | The trim or package the maker sells, e.g. "R-Line". |
variant | nice | The version badge from the ad title, e.g. "4Motion" or "320d". |
price | nice | Your asking price in EUR. Adds vsMarket to the answer. |
excludeListings | nice | Listings to leave out, e.g. your own ad: a link, "nj:51415144" or an id. |
confidence is at most medium.Which field does what
Take this car: Volkswagen Golf 7, 2.0 TDI, 4Motion, R-Line, diesel, 2017, 160,000 km.
| it goes in | value | meaning |
|---|---|---|
brand | Volkswagen | The maker. |
model | Golf | Only the name. Not Golf 7, not Golf 2.0 TDI. |
year | 2017 | The year already tells the generation, so you do not need to say 7. |
engine | 2.0 | Engine size. |
fuel | diesel | 2.0 alone cannot tell a diesel from a petrol. |
variant | 4Motion | A badge that engine and fuel cannot say. On BMW and Audi it is the power badge: 320d, 40 TDI. |
equipmentLine | R-Line | The trim. Some trims sell about 10 percent higher than the rest. |
Not sure which model names we accept? Ask us, it is free:
curl "https://carradar.app/api/v1/vehicle-api/models?brand=Volkswagen" \
-H "Authorization: Bearer crk_live_..."
{
"status": "ok",
"brand": "Volkswagen",
"models": [
{ "model": "Golf", "listings": 57580 },
{ "model": "Passat", "listings": 33389 },
{ "model": "Tiguan", "listings": 31264 }
]
}If model has more than the name, we refuse and tell you what to move. Nothing is charged.
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "model_has_extra_words",
"message": "We read this as \"Golf\". Send only the model name in `model`, and put the rest in `variant` (for example 320d or 4Motion), `engine`, `fuel` or `equipmentLine`.",
"model": "Golf",
"extraWords": ["7", "2.0", "TDI"]
}
}Electric cars have no engine size. Send fuel: "electric" and leave engine out. If you send one anyway we ignore it and list it under unappliedFilters. We also recognise electric-only models such as the ID.3 on our own.
Which years and kilometres are compared
We compare with your own year. If that year has fewer than 5 cars we add one year on each side, and only as a last resort two. We never widen across a generation change. For kilometres we use a window of 25,000 km either side of your figure, opened up when there are too few cars. The windows we used are in filters.yearRange and filters.mileageRange. To fix them yourself, send yearFrom and yearTo, or mileageMin and mileageMax: those are used exactly as sent.
What comes back
| field | meaning |
|---|---|
status | ok, or insufficient_data when there are too few similar cars. That is an answer, not an error, and it is free. |
price.suggested | The middle price of similar cars. |
price.low, price.high | The middle half of the prices. Most cars sit between these. |
confidence | How sure we are. See below. |
comparables | How many cars the price is based on. |
filters | What we compared against: years, kilometres, engine, fuel, trim. |
comparableLines | Which trims the similar cars have. See Trims in the market. |
vsMarket | Only if you sent price: how far above or below the market you are. |
timeOnMarket | How many days cars like this stay listed. Half leave within medianDays. It is not a promise for one car. |
unappliedFilters | Values we could not use, for example a fuel we do not know. |
| confidence | meaning |
|---|---|
high | 8 or more similar cars and nothing had to be loosened. |
medium | 8 or more cars, but we loosened something: wider years or kilometres, a dropped word, or no engine sent. |
low | 3 to 7 cars. |
none | No price. |
With price you also get vsMarket: your price against the market median, in euros and percent. It never changes the suggested price.
Trims in the market
When you send no equipmentLine, we show which trims the similar cars have, and a median price for each. A trim is shown only when at least 5 cars have it.
"comparableLines": {
"lines": [
{ "line": "R-Line", "count": 5, "medianPrice": 12499 }
],
"unknown": { "count": 34, "medianPrice": 11895 },
"otherLinesCount": 0
}Read it: 5 cars are R-Line and sell around 12,499 EUR. 34 cars do not name a trim in the ad title and sell around 11,895 EUR. unknown does not mean base trim. Many sellers just do not write the trim.
If you send an equipmentLine, we compare only with cars that have it, and this block is left out. If no car has it, we give it up and say so. The price is then for cars without that trim, so tell your user.
"filters": {
"droppedWords": [ { "token": "Scout", "equipmentLine": true } ],
"equipmentLineMissing": true
}Price many cars
Use this for a stock list. It returns full market analytics for each car. Steps: send the cars, wait a few seconds, read the results.
Up to 50 cars per call. The answer is 202 Accepted with a job id straight away, and the work runs in the background. A 200 car stock is four calls.
curl -X POST https://carradar.app/api/v1/vehicle-api/jobs \
-H "Authorization: Bearer crk_live_..." \
-H "Content-Type: application/json" \
-d '{
"market": "HR",
"vehicles": [
{ "ref": "stock-1", "brand": "Audi", "model": "A4",
"year": 2018, "mileage": 140000,
"engine": "2.0", "fuel": "diesel", "variant": "40 TDI",
"price": 18900 },
{ "ref": "stock-2", "brand": "BMW", "model": "3 Series",
"year": 2016, "mileage": 170000,
"engine": "2.0", "fuel": "diesel", "variant": "320d",
"equipmentLine": "M Sport" }
]
}'HTTP/1.1 202 Accepted
{
"jobId": "7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913",
"vehicles": 2,
"groups": 2,
"status": "queued",
"estimatedSeconds": 4
}Each car uses the same fields as the price endpoint, with two differences: ref is required and must be unique inside the call, and you may also send family, generation, keyword, trendWindow, listingUrl and an excludeListings for that car only. Next to market you can send excludeListings for all cars at once, for example your whole stock, plus ownListings and webhookUrl.
excludeListings on the whole call changes prices: your stock is removed from every comparison.A car with missing data is not a failure
If a car has no year or no mileage, only that car is rejected. The other cars are still priced. The rejected car comes back as invalid_input and is free. A car we do not know comes back as unresolved with close matches, also free.
{
"ref": "stock-9",
"resolution": {
"status": "invalid_input",
"missing": ["year"],
"message": "Send `year`, or both `yearFrom` and `yearTo`."
}
}Read a job
Repeat every 5 seconds until status is done. It goes queued, running, then done or failed. Results that are ready can be read while it runs. Match them to your cars with ref, never by position. Results stay readable for 7 days, and only with the key that created the job.
curl https://carradar.app/api/v1/vehicle-api/jobs/7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913 \ -H "Authorization: Bearer crk_live_..."
{
"jobId": "7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913",
"status": "running",
"groups": 2,
"groupsDone": 1,
"vehicles": 2,
"results": [
{ "ref": "stock-1", "billed": true,
"resolution": { "status": "resolved", "family": "A4" },
"yearBand": { "from": 2018, "to": 2018, "n": 21 },
"comparableLines": { /* ... */ },
"vsMarket": { /* ... */ },
"analytics": { /* ... */ } }
]
}
// stock-2 is in a group that has not finished yet, which is why it is
// absent from results so far.Only a few cars
Up to 3 cars. It answers straight away when the figures are ready. If not, it answers with a job id and servedInline: false, and you read the job a few seconds later.
What comes back for each car
| field | meaning |
|---|---|
ref | Your id for the car. |
billed | True if this car cost a request. |
resolution | How we read your model: resolved, unresolved or invalid_input. |
precision | The words we matched on and the words we gave up. A given up trim has equipmentLine: true. |
yearBand, mileageBand | The year and kilometre windows used, and whether we widened them. |
comparableLines | Which trims the similar cars have, with a median per trim. Only when you sent no equipmentLine. |
vsMarket | Only if you sent price: suggestedPrice, deltaEur, deltaPct, p25 and p75. |
analytics | The market numbers, in the blocks below. |
"vsMarket": {
"askingPrice": 29900,
"suggestedPrice": 27450,
"deltaPct": 8.9,
"deltaEur": 2450,
"p25": 26725,
"p75": 29249
}| analytics block | answers |
|---|---|
overview | The headline: price percentiles, how many good deals, how fast cars sell, and a plain verdict. |
market | Price bands, how much supply there is, how easy it is to sell, and how price drops with age. |
opportunity | Where each similar car sits, price against kilometres, and how many are good deals or overpriced. |
timing | How hot the market is, and how ads age. |
profit | A buy and resell estimate: margin, profit, turns per month. |
fleet | Whether the market can absorb a multi-car purchase. |
trend | Price over time. |
marketPower | How many similar cars there are, and whether that is enough to trust the numbers. |
listings | A few similar cars: site, title, link, price, kilometres, year. |
Prices are in EUR. A block your key does not include comes back as { available: false }, never as an empty object.
A small market is an answer, not an error. marketPower.level says uncontested (nothing similar is listed), monopoly (too few for a median), thin (numbers are only a guide) or competitive. Few similar cars often means you have pricing power. marketPower.text is a ready sentence for your user.
Cost and usage
- Price one car: an answer with a price is one request. An answer without a price, an error, and the same question asked again within 24 hours are free.
- Price many cars: each car with a market is one request. Free: invalid_input, unresolved, no similar cars at all, only your own ad as the comparable, reading a job, and errors.
- Every batch result says
billed, so you can check your invoice line by line.
{
"month": "2026-08",
"plan": "monthly",
"calls": 7,
"deduped": 0,
"billedCents": 70,
"pricePerCallCents": 10,
"limit": 5000,
"remaining": 4993,
"resetsAt": "2026-09-01T00:00:00.000Z"
}On a monthly plan limit and remaining are filled in and calls past the limit are refused. On pay as you go both are null.
Webhooks
For batches only. Send webhookUrl with a job and we push results to it instead of making you poll: one call per group as it finishes, and one when the job is done.
POST https://your-server.example/carradar
Content-Type: application/json
X-CarRadar-Job: 7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913
X-CarRadar-Signature: sha256=9f2b1c...
{
"jobId": "7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913",
"event": "group.completed",
"status": "running",
"vehicles": 3,
"groups": 2,
"groupsDone": 1,
"results": [ { "ref": "A-101", "cached": false, "analytics": { /* ... */ } } ]
}The URL must be https and public. Every delivery is signed with the webhook secret issued with your key, as an HMAC-SHA256 of the exact bytes we sent. Verify it against the raw body, before any JSON parsing.
import crypto from "node:crypto";
app.post("/carradar", express.raw({ type: "application/json" }), (req, res) => {
const expected =
"sha256=" +
crypto.createHmac("sha256", process.env.CARRADAR_WEBHOOK_SECRET)
.update(req.body) // the RAW bytes, not the parsed object
.digest("hex");
const got = req.get("X-CarRadar-Signature") ?? "";
const ok =
got.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
const payload = JSON.parse(req.body.toString("utf8"));
res.sendStatus(200); // answer fast, process after
});Answer with any 2xx. Anything else is retried with exponential backoff. A slow webhook never delays your results, which stay readable from the job endpoint.
Claude and other AI assistants (MCP)
The same backend speaks the Model Context Protocol, so you can connect it to Claude, ChatGPT, Gemini or any MCP client and ask about cars in plain language. The assistant uses the same endpoints, key and billing.
https://carradar.app/api/v1/vehicle-api/mcp
A client that lets you set a request header sends your API key. A client that does not, which includes every assistant that runs in a browser, signs in through OAuth. Both end up on the same key, limits and ledger.
Claude in the browser
Open Settings, then Connectors, then Add custom connector, and paste the address above. Leave the OAuth fields empty. Claude sends you to CarRadar to sign in, shows which API key it will bill, and the tools appear in your next conversation. Connecting is free.
Claude Code and desktop clients
These let you set an Authorization header, so they take the API key directly and skip the sign-in.
claude mcp add --transport http carradar \ https://carradar.app/api/v1/vehicle-api/mcp \ --header "Authorization: Bearer crk_live_..."
{
"mcpServers": {
"carradar": {
"type": "http",
"url": "https://carradar.app/api/v1/vehicle-api/mcp",
"headers": { "Authorization": "Bearer crk_live_..." }
}
}
}To check it worked, ask the assistant what it has used this month. If it answers with a usage figure, the key is being sent correctly.
ChatGPT, Gemini and everything else
A client that follows the MCP authorization specification connects with only the address above. If it asks for OAuth details by hand, these are the values.
server url https://carradar.app/api/v1/vehicle-api/mcp authorization url https://carradar.app/oauth/authorize token url https://carradar.app/api/v1/oauth/token registration url https://carradar.app/api/v1/oauth/register revocation url https://carradar.app/api/v1/oauth/revoke issuer https://carradar.app scope vehicle-api pkce S256, required client authentication none, client_secret_post or client_secret_basic
A client that cannot register itself needs a client ID, and a confidential client needs a secret too. Ask at [email protected] and say which assistant it is for.
What the assistant can do
| tool | does | cost |
|---|---|---|
suggest_price | Price one car. Same fields as the price endpoint. | 1 per answer with a price |
lookup_vehicle | Full analytics for up to 3 cars. | 1 per car |
submit_vehicle_batch | Queues up to 50 cars. | 1 per car |
get_vehicle_job | Collects a batch, including partial results. | free |
resolve_model | Checks how a model name is read. | free |
get_api_usage | Spend and what is left this month. | free |
For example: "what is a 2017 Golf 2.0 diesel with 160,000 km worth in Serbia?" The assistant fetches the figures and reads them back.
Disconnecting
Remove the connector in the assistant and it revokes its own access. Revoking the API key also ends every connection made with it. One key is one customer: whoever holds it can spend against it, so ask for a key per person if you need separate accounting.
If a connector will not connect
Run these three requests in order and stop at the first that does not answer as described. None of them needs a credential.
# 1. the endpoint answers, and says how to authenticate curl -i -X POST https://carradar.app/api/v1/vehicle-api/mcp # expect 401 with a WWW-Authenticate header naming resource_metadata # 2. the resource metadata that header points at curl -i https://carradar.app/.well-known/oauth-protected-resource/api/v1/vehicle-api/mcp # 3. the authorization server it names curl -i https://carradar.app/.well-known/oauth-authorization-server
- Told to sign in again right after signing in. The account has no active API key, or its key was revoked. Ask us for a key.
- The address was typed by hand. Use exactly the address above, with no trailing slash and no
www. - Everything answers and it still fails. Send us the reference id the assistant shows (for Claude it starts with
ofid_) and the time you tried.
Limits and errors
| limit | value |
|---|---|
| Price endpoint, live key | 10 calls per second, 120 per minute |
| Price endpoint, sandbox key | 1 call per second, 30 per minute, 1000 in total |
| Cars per batch | 50 |
| Cars per inline lookup | 3 |
| Batch submissions | 30 per minute |
| Inline lookups | 60 per minute |
| Job reads | 240 per minute, free |
| Model names and model check | 100 per minute, free |
| Result retention | 7 days |
Limits are counted per key, not per IP. We answer most uncached price calls in 0.2 to 2 seconds, and a car nobody asked about yet can take longer, so set your timeout to 20 seconds.
HTTP/1.1 429 Too Many Requests
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}| status | meaning |
|---|---|
| 400 | The request is wrong, for example no year or mileage. The message names the field. |
| 401 | Missing, unknown or revoked key. |
| 403 | The key cannot use this endpoint, is suspended, or has expired. |
| 404 | No such job, or a job that belongs to another key. |
| 413 | Too many cars in one call. |
| 422 | We do not know this model (unresolved_model, with close matches), or model has extra words (model_has_extra_words). |
| 429 | Rate limited or allowance used. Wait retryAfterSeconds. |
| 503 | Busy or refreshing. Not charged. Retry after retryAfterSeconds. |
Every night from about 04:45 to 05:30 (Belgrade time) our data is rebuilt and new calculations wait. Price calls then answer 503 refresh_window, unless the same question was already answered that day. Batch jobs are accepted and run when it ends.
Using the data
The analytics are yours to use inside your business: pricing your stock, valuing trade-ins, building your own dashboards and reports.
You may not rebuild the underlying listing database or resell the raw data as a competing product. The full wording is in the API section of our Terms of Service, and how we handle data you send is in our Privacy Policy.
Do not put customer names, phone numbers, plates or VINs tied to an owner in the ref field. Use your own stock number.