The comparable vehiclesendpoint
GET /v1_2/listings/comparables takes one subject vehicle - by id or by vin - and returns the cohort around it: the cohort key it built, how many listings are in it, price and odometer distributions, and a set of nearest-price sample listings. 92.8% of the catalog carries an asking price. One call is 10 millicredits.
How do I find comparable vehicle listings for one car?
Call GET /v1_2/listings/comparables with either id or vin naming the subject vehicle; sending neither answers 400 id_or_vin_required. The response keeps its own shape rather than the data plus meta envelope: subject echoes the vehicle you asked about, cohort names the year, make, model, trim and state the comparison was built on, count gives the cohort size, and price_stats and odometer_stats each carry count, min, max, mean, median, p25 and p75. samples returns nearest-price listings drawn from the cohort, up to 50 of them, defaulting to 10. Two switches tighten the match: same_trim restricts the cohort to the subject's trim and same_state restricts it to the subject's state, both defaulting to false. The call is scan class at 10 millicredits.
The cohort is built for you, and it tells you what it built
You do not assemble a comparison set by hand. Name a subject listing and the endpoint returns the cohort key it used - year, make, model, trim and state - next to the distributions. Read that key before you read the numbers: it is the difference between a defensible comparison and an average taken across three trims and two provinces.
same_trim and same_state are the two dials that matter
Both default to false, so the out-of-the-box cohort is deliberately wide. Set same_trim=true where trim drives the money, which on a truck or a luxury sedan it usually does, and same_state=true when you need a local figure rather than a national one. Each narrows the cohort, so watch count as you go: a tight cohort of 6 listings is a worse guide than a loose one of 200.
Cohort count and price count are different numbers
price_stats.count is how many listings in the cohort actually carry a price, and it is not the cohort's own count - 92.8% of the catalog has an asking price, so the rest sit inside the cohort without contributing to the price distribution. odometer_stats.count works the same way. A missing value is absent rather than zero, so nothing silently drags a mean toward the floor.
Sample rows are plain listings, with no dealer identity
samples is capped at 50 and defaults to 10, and each entry is a lightweight listing: id, sale_price, odometer, province_state_code, city. These rows are not enriched with dealer_site_id or dealer_id even on v1.2, because comparables mirrors the v1 handler exactly. To find out who is advertising the comparable cars, run a search filtered by site_id or dealer_id instead.
Frequently asked questions
How does the comparables endpoint choose comparable vehicles?
It builds a cohort from the subject listing you name with id or vin, keyed on year, make, model, trim and state, and returns that key alongside the results so the basis is never hidden. By default the cohort is wide, since same_trim and same_state both default to false; set either to true to tighten it. The response reports the cohort's count, so a well-populated comparison can be told from a thin one before anyone acts on it.
What statistics does the comparables API return?
Two distributions. price_stats and odometer_stats each carry count, min, max, mean, median, p25 and p75 across the cohort. Alongside them come the subject vehicle, the cohort key, the cohort count, and a samples array of the nearest-price listings - up to 50, with 10 returned by default. The count inside each distribution counts only listings carrying that field, which is lower than the cohort count.
Can I get comparables from a VIN?
Yes. Pass vin instead of id and the endpoint resolves the subject that way. Supply one or the other, since a call with neither answers 400 id_or_vin_required. If you are starting from a VIN and want both the car and its market position, one call on the vehicles route plus one comparables call together cost 11 millicredits - a little over one hundredth of a credit.
How much does a comparables call cost?
10 millicredits per call, the scan-class charge, so 100 comparison calls per credit. That price is flat regardless of how large the cohort turns out to be or how many samples you request. Errors are refunded, and the listings API carries no subscription and no minimum spend.
More vehicle listings
Try Hermes Data for $0.99
Self-serve access to the automotive data your business runs on. The $0.99 trial gives you 20 credits to spend across Contacts, Dealers, and Dealer Groups. Then auto-upgrade to Starter ($99/mo) — or cancel any time.
Contacts, Dealers, and Dealer Groups are all self-serve on one credit wallet — spend your trial credits on any of them. Vehicle Listings is live too, on its own API subscription (separate from the credit wallet). Explore Listings.