The vehicle listingssearch API
The main query over the catalog: 19,349,581 live listings from 67,091 dealer websites across 63 states and provinces. Send filters as query parameters, read rows out of data, and page with the cursor in meta. One call returns up to 1,000 rows and costs 10 millicredits per 100 rows returned.
What does the vehicle listings search endpoint return?
GET /v1_2/listings/search returns matching vehicle listings in a data array with a meta object beside it, where meta carries page, page_size, total and next_cursor. Filters go in the query string and every one of them ANDs with the rest: make, model, trim, year_min and year_max, price_min and price_max, odometer_min and odometer_max, state, city, postal_code, body_style, fuel, certified, new_vehicle, dealer_netloc, and the geo triple lat, lon and radius_km. Rows are sparse, meaning only fields that carry a value are present, and id is the one key you can always count on. sort accepts relevance, price_asc, price_desc, odometer_asc, odometer_desc, year_desc and distance. Search is a scan-class call charged 10 millicredits per started 100 rows returned, and 1 credit is 1000 millicredits, so it works out to 10,000 listings per credit at any page size. There is no subscription, and 4xx and 5xx responses are refunded.
Filters are AND, and the units are the listing's own
price_min and price_max compare against the raw sale_price - USD on a US listing, CAD on a Canadian one - and odometer_min and odometer_max compare against a raw odometer that is miles in the US and kilometres in Canada. Nothing is converted at ingest, so a cross-border range filter is comparing two different units, and sort=price_asc orders USD and CAD in one list. Read province_state_code to know which you have, or scope to one country first.
Cursor paging has no depth limit
Numbered pages stop at max_offset, published live at GET /v1_2/listings/meta and currently 10,000; going past it is 400 offset_too_deep, because reaching page N by number means counting to it. Every paged response carries meta.next_cursor, and sending it back as cursor resumes exactly where the last page stopped - at any depth, for no extra charge. Keep the route, sort and filters identical across the walk, never send page and cursor together, and restart on 400 snapshot_expired.
A geo search silently drops listings with no coordinates
latitude and longitude come from the selling rooftop, and about 15% of the catalog has none. Supply lat, lon and radius_km and every one of those listings is excluded whatever else it matched, with meta.total reporting only the reduced set and no separate count of what was dropped. The gap is uneven by market: under 5% in QC, over 30% in YT, NB, MB, AK and MT. Run the same query without the geo triple and compare to tell 'outside the radius' from 'location unknown'.
Charged by the 100 rows you take, not by the call
page_size runs 1 to 1000 and defaults to 25. Ask for more than 1000 and it is clamped silently and echoed back at 1000, so read meta.page_size rather than assuming your value was honoured. A search is charged 10 millicredits for every started 100 rows it actually returns: 1 row and 100 rows both cost 10, 250 rows cost 30, and a full 1000-row page costs 100. The per-row price is the same at every width, so a wide page does not save credits - it saves round trips and rate-limit headroom, and it is billed on the rows that arrive rather than the number you asked for.
Compliance & sourcing
You may build derived products on top of the listings data - a vehicle-pricing API, market analytics, valuation models, merchandising tools - under our terms of service. What you may not do is resell, redistribute, or expose the raw listings themselves, or a substantial portion of them, in a form that lets a third party pull them back out as a standalone dataset. Two safety limits also apply to every key: 100 requests per second, and a spend ceiling of 120 credits per minute. Each answers 429 with a Retry-After header.
Frequently asked questions
What does the vehicle listings search API return?
A JSON object with a data array of listing rows and a meta object holding page, page_size, total and next_cursor. total is the full match count across the catalog, not the number of rows on the page. Rows are sparse: only fields carrying a value appear, so id is the only key guaranteed to be there. Every row names the dealer website it came from, and names the dealership behind that website wherever we can resolve it.
How do I page past 10,000 vehicle listings?
Switch from numbered pages to the cursor. page multiplied by page_size is capped by max_offset, which the API publishes at GET /v1_2/listings/meta and which is currently 10,000; a deeper request answers 400 offset_too_deep. Instead, read meta.next_cursor off each response and send it back as the cursor parameter. There is no depth limit, the ten-thousandth page costs what the first one did, and page and cursor cannot be sent together.
How much does one vehicle listings search call cost?
10 millicredits, one hundredth of a credit, for every started 100 rows the call returns - so 1 row and 100 rows both cost 10 millicredits, and the maximum 1000-row page costs 100. That works out to 10,000 listings per credit at any page size. There is no subscription, and any call ending in a 4xx or 5xx error is refunded, so failed calls never cost credits.
Can I search vehicle listings by location radius?
Yes. Supply lat, lon and radius_km together - all three or none - and each result comes back with distance_km, always in kilometres in both countries, with sort=distance ordering nearest first. radius_km must be positive and no larger than max_radius_km from the meta route. Listings with no coordinates on file, roughly 15% of the catalog, are excluded from any radius search.
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.