How DealScore grades work
A DealScore grade rates a used car's asking price by how far it sits from the expected price of comparable US dealer listings. Great is 10% or more below expected, Fair is within 3% either way, and Overpriced is more than 10% above. When comps are too thin, it returns cannot_score instead of a grade.
The core number: delta_pct
Every score starts with one ratio. delta_pct = (asking_price - expected_price) / expected_price. Negative means the ask is below market; positive means above.
Expected price comes from dealer listing comps. The default score uses US national inventory. ZIP is optional local refine. Production at cardealscore.com uses live comps (data_source: live). Local dev may use deterministic mock data instead. Comps are US dealer listings, so a private-party price is judged against dealer prices for comparable cars.
score_v2 grade bands
Rubric version score_v2 turns delta_pct into one of five grades and a 0 to 100 score. Each grade has its own score range: Great 90 to 100, Good 75 to 89, Fair 60 to 74, High 40 to 59, Overpriced 0 to 39. Inside a range, a lower price scores higher, and only a price 20% or more under expected scores 100.
| Grade | delta_pct | Score | Meaning |
|---|---|---|---|
| Great | ≤ -10% | 90 to 100 | Asking well below expected market value. |
| Good | ≤ -3% | 75 to 89 | Asking modestly below market. |
| Fair | ≤ +3% | 60 to 74 | Roughly in line with comps. |
| High | ≤ +10% | 40 to 59 | Asking above market, but not wildly so. |
| Overpriced | > +10% | 0 to 39 | Asking well above what comps support. |
Want the math without scoring a car? POST /api/explain accepts a delta_pct and returns the grade breakdown.
Live comps vs. cannot_score
Production fetches fresh comps on each score request. We don't cache across requests; each call is independent.
- scored: enough nearby comps to compute expected price and a grade.
- cannot_score: live data unavailable, upstream failed, rate limits hit, or comps are too thin. No silent fallback to mock data.
- partial: mock mode only (dev). Fine for local testing, not production truth.
Confidence adjusts with comp count and whether data is live or mock. Fewer comps mean lower confidence, even when we can score.
Quick answers
- How is the DealScore grade calculated?
- DealScore computes delta_pct = (asking_price - expected_price) / expected_price, where expected_price comes from comparable US dealer listings. It then maps delta_pct to a grade: Great at -10% or lower, Good up to -3%, Fair up to +3%, High up to +10%, and Overpriced above +10%.
- What does a Great grade mean?
- Great means the asking price is 10% or more below the expected price from comparable dealer listings. A Great grade scores 90 to 100.
- What price counts as Fair?
- Fair means the asking price is more than 3% below and at most 3% above the expected price. A Fair grade scores 60 to 74.
- Is a higher score better?
- Yes. The score runs from 0 to 100, and a lower asking price scores higher. Only a price 20% or more under expected scores 100.
- Why would DealScore return cannot_score?
- cannot_score means DealScore could not compute a reliable expected price, so it gives no grade. The usual causes are live comps being unavailable, the data request failing or hitting a rate limit, too few comparable listings, or input it cannot use, such as an asking price of zero. It never falls back to mock data, and a cannot_score result does not count toward the monthly meter.
- What does confidence mean?
- confidence is a number from 0 to 1 that rises with comps_count. On live data it is 0.92 with 12 or more comps, 0.82 with 6 to 11, 0.68 with 3 to 5, and 0.5 below 3.
What we don't do
- No Facebook Marketplace or Craigslist URL fetch. Send year/make/model (or a VIN), asking price, and mileage. ZIP is optional.
- comps_count is the number of listings the grade used.
- No cross-request comp caching. Each call is independent.
See also: whether a price is a fair deal, scoring by VIN, scoring with an agent, or call the API from an agent.