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 carPrice many cars
ForA listing form, a quick checkA stock list
You getA suggested price with a low and a highFull market analytics for each car
HowOne call, the answer comes straight backSend up to 50 cars, then read the results
RoutePOST /vehicle-api/price-suggestionPOST /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

base url
https://carradar.app/api/v1

Every request carries your key as a bearer token. Nothing else is needed.

header
Authorization: Bearer crk_live_...
Treat the key like a password. Keep it on your server, never in a browser or a mobile app. If it leaks, we revoke it and issue a new one.

Price one car

POST/vehicle-api/price-suggestion1 request per answer with a price

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.

request
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
  }'
200 OK
{
  "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.

fieldneedwhat to put
marketmustCountry: RS, BA, HR, SI, DE, CH or NLBE. Ask your user, do not guess.
brandmustThe maker, e.g. "Volkswagen". "VW" also works.
modelmustThe model name only, e.g. "Golf".
yearmustModel year. Or send yearFrom and yearTo.
mileagemustKilometres. Or send mileageMin and mileageMax.
engineshouldEngine size in cc or litres, e.g. "1968" or "2.0". Not for electric cars.
fuelshould"petrol", "diesel", "hybrid" or "electric".
transmissionshould"manual" or "automatic".
equipmentLineniceThe trim or package the maker sells, e.g. "R-Line".
variantniceThe version badge from the ad title, e.g. "4Motion" or "320d".
priceniceYour asking price in EUR. Adds vsMarket to the answer.
excludeListingsniceListings to leave out, e.g. your own ad: a link, "nj:51415144" or an id.
Without year or mileage the call fails with a clear message. Without engine you still get a price, but for every engine of that model, so 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 invaluemeaning
brandVolkswagenThe maker.
modelGolfOnly the name. Not Golf 7, not Golf 2.0 TDI.
year2017The year already tells the generation, so you do not need to say 7.
engine2.0Engine size.
fueldiesel2.0 alone cannot tell a diesel from a petrol.
variant4MotionA badge that engine and fuel cannot say. On BMW and Audi it is the power badge: 320d, 40 TDI.
equipmentLineR-LineThe trim. Some trims sell about 10 percent higher than the rest.

Not sure which model names we accept? Ask us, it is free:

model names
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.

422
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

fieldmeaning
statusok, or insufficient_data when there are too few similar cars. That is an answer, not an error, and it is free.
price.suggestedThe middle price of similar cars.
price.low, price.highThe middle half of the prices. Most cars sit between these.
confidenceHow sure we are. See below.
comparablesHow many cars the price is based on.
filtersWhat we compared against: years, kilometres, engine, fuel, trim.
comparableLinesWhich trims the similar cars have. See Trims in the market.
vsMarketOnly if you sent price: how far above or below the market you are.
timeOnMarketHow many days cars like this stay listed. Half leave within medianDays. It is not a promise for one car.
unappliedFiltersValues we could not use, for example a fuel we do not know.
confidencemeaning
high8 or more similar cars and nothing had to be loosened.
medium8 or more cars, but we loosened something: wider years or kilometres, a dropped word, or no engine sent.
low3 to 7 cars.
noneNo 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
"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.

a trim nobody has
"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.

POST/vehicle-api/jobs1 request per car

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.

request
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" }
    ]
  }'
response
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.

invalid_input
{
  "ref": "stock-9",
  "resolution": {
    "status": "invalid_input",
    "missing": ["year"],
    "message": "Send `year`, or both `yearFrom` and `yearTo`."
  }
}

Read a job

GET/vehicle-api/jobs/{jobId}free

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.

request
curl https://carradar.app/api/v1/vehicle-api/jobs/7f1c0a2e-5d31-4a6e-9c0b-2b41d7e5a913 \
  -H "Authorization: Bearer crk_live_..."
200 OK, still running
{
  "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

POST/vehicle-api/vehicles:lookup1 request per car

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

fieldmeaning
refYour id for the car.
billedTrue if this car cost a request.
resolutionHow we read your model: resolved, unresolved or invalid_input.
precisionThe words we matched on and the words we gave up. A given up trim has equipmentLine: true.
yearBand, mileageBandThe year and kilometre windows used, and whether we widened them.
comparableLinesWhich trims the similar cars have, with a median per trim. Only when you sent no equipmentLine.
vsMarketOnly if you sent price: suggestedPrice, deltaEur, deltaPct, p25 and p75.
analyticsThe market numbers, in the blocks below.
vsMarket
"vsMarket": {
  "askingPrice": 29900,
  "suggestedPrice": 27450,
  "deltaPct": 8.9,
  "deltaEur": 2450,
  "p25": 26725,
  "p75": 29249
}
analytics blockanswers
overviewThe headline: price percentiles, how many good deals, how fast cars sell, and a plain verdict.
marketPrice bands, how much supply there is, how easy it is to sell, and how price drops with age.
opportunityWhere each similar car sits, price against kilometres, and how many are good deals or overpriced.
timingHow hot the market is, and how ads age.
profitA buy and resell estimate: margin, profit, turns per month.
fleetWhether the market can absorb a multi-car purchase.
trendPrice over time.
marketPowerHow many similar cars there are, and whether that is enough to trust the numbers.
listingsA 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.

Lists are capped: at most 50 scatter points and 5 listings per list. You are buying analytics, not a copy of the listing database. The Terms say so.

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.
GET/vehicle-api/usage?month=YYYY-MMfree
200 OK
{
  "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.

delivery
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.

verifying, node
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.

server address
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.

You need an API key before you can connect. Ask for one at [email protected].

Claude Code and desktop clients

These let you set an Authorization header, so they take the API key directly and skip the sign-in.

command line
claude mcp add --transport http carradar \
  https://carradar.app/api/v1/vehicle-api/mcp \
  --header "Authorization: Bearer crk_live_..."
json config
{
  "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.

oauth details
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

tooldoescost
suggest_pricePrice one car. Same fields as the price endpoint.1 per answer with a price
lookup_vehicleFull analytics for up to 3 cars.1 per car
submit_vehicle_batchQueues up to 50 cars.1 per car
get_vehicle_jobCollects a batch, including partial results.free
resolve_modelChecks how a model name is read.free
get_api_usageSpend 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.

check the server from anywhere
# 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

limitvalue
Price endpoint, live key10 calls per second, 120 per minute
Price endpoint, sandbox key1 call per second, 30 per minute, 1000 in total
Cars per batch50
Cars per inline lookup3
Batch submissions30 per minute
Inline lookups60 per minute
Job reads240 per minute, free
Model names and model check100 per minute, free
Result retention7 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.

over the rate limit
HTTP/1.1 429 Too Many Requests

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}
statusmeaning
400The request is wrong, for example no year or mileage. The message names the field.
401Missing, unknown or revoked key.
403The key cannot use this endpoint, is suspended, or has expired.
404No such job, or a job that belongs to another key.
413Too many cars in one call.
422We do not know this model (unresolved_model, with close matches), or model has extra words (model_has_extra_words).
429Rate limited or allowance used. Wait retryAfterSeconds.
503Busy 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.