Documentation

Overview

Vehicle Listings tells you what cars are for sale right now, and who is selling them. It is a read-only REST API over used and new vehicle inventory advertised by dealerships across the US and Canada. Ask it three kinds of question: search the catalog with filters, look up one vehicle by id or VIN, or get summary stats for a market. This version also tells you which dealership each car belongs to, and keeps records for about 90 days after a car leaves the market - so you can see what it sold for and how its price moved.

Quickstart

Two steps. Create an API key on the API key page, then run the request below. It searches live inventory and returns the matching listings in data, with the match count and paging info in meta.

curl "https://luxe.hermesdata.io/v1_2/listings/search?make=Toyota&model=RAV4&year_min=2023&page_size=3" \
  -H "Authorization: Bearer hd_live_your_key_here"

{
  "data": [
    {
      "id": "v_77c1e0",
      "vin": "2T3P1RFV8SC123456",
      "make_name": "Toyota",
      "model_name": "RAV4",
      "trim_name": "XLE",
      "year": 2025,
      "sale_price": 34210,
      "odometer": 8,
      "province_state_code": "TX",
      "city": "Austin",
      "dealer_netloc": "exampletoyota.com",
      "dealer_site_id": "7d24c0e918b6a53f42910cd7e6b38f5a",
      "dealer_id": "d_44b19e",
      "entity_dealer_id": "d_44b19e",
      "new_vehicle": true,
      "first_seen": "2026-07-24"
    },
    {
      "id": "v_5ab902",
      "make_name": "Toyota",
      "model_name": "RAV4",
      "trim_name": "Limited",
      "year": 2024,
      "sale_price": 31995,
      "odometer": 12480,
      "province_state_code": "TX",
      "city": "Dallas",
      "dealer_netloc": "northsideauto.example",
      "dealer_site_id": "e05b6c37a91d4f28b3c7069e5a1d82f4",
      "certified": true,
      "first_seen": "2026-07-11"
    }
  ],
  "meta": { "page": 1, "page_size": 3, "total": 862, "next_cursor": "eyJ2IjoiMDgzMTk2…" }
}
// Two rows, two states of dealer identity: the first resolved to a dealership
// entity, the second did not, so its dealer_id key is absent entirely. Both
// carry dealer_site_id - that one is always there.

That is the whole setup - there is no sandbox and no test key, you call live data from the first request. It costs credits: paging search results runs about 10,000 listings per credit, and a single lookup by id or VIN is the cheapest call there is. From here, browse the full API reference or see every field in the data schema.

Authentication

Send your API key as a bearer token on every /v1_2/listings/* request. The key identifies you, resolves to your shared credit wallet, and carries its own rate limit (100 requests/second).

Authorization: Bearer hd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate and manage your key from the API key page. Keep it secret - you only see it in full once. Auth fails closed: an empty or frozen wallet is refused. The liveness probe GET /health needs no key. One key covers both versions - nothing to re-issue or re-provision to move from /v1 to /v1_2.

Conventions

These rules hold across every endpoint.

Units

The catalog spans the US and Canada, and values are passed through in the units the listing was published in - nothing is converted at ingest. Read province_state_code to know which you have:

The practical consequences: a cross-border price_min/price_max or odometer_min/odometer_max filter compares raw numbers across two units, and sort=price_asc orders USD and CAD in one list. Filter to one country (or convert on your side) when that matters. Aggregates from the stats endpoints inherit the same mix.

Response envelopes

You'll get one of three shapes, depending on the endpoint:

Pagination

For most uses, numbered pages are all you need: send page (1-based) and page_size (1–1000, default 25), and read meta.total for how many rows matched in total. A page_size over 1000 is silently reduced to 1000 and echoed back at that value, so read the echo rather than assuming your number was used.

Search-style calls (the scan price class - see Metering) are billed on rows returned, rounded up to the next 100: 1 row and 100 rows both cost one unit, 250 rows cost three, 1000 rows cost ten. The per-row price is the same at any page_size, so asking for a bigger page saves round trips, not credits.

Only if you need to walk every result: numbered pages stop at max_offset (see /meta) - go past it and you get 400 offset_too_deep. To go deeper, page by cursor instead: every paged response carries meta.next_cursor, and sending it back as ?cursor=… resumes exactly where the last page stopped. There is no depth limit and no extra charge - the ten-thousandth page costs what the first one does. Keep the route, sort and filters identical across the walk (a mismatch is 400 invalid_cursor), don't send page and cursor together, and treat the token as opaque. Cursors are pinned to a catalog snapshot: if the nightly rebuild lands mid-walk you get 400 snapshot_expired naming the new version, rather than silently skipped or repeated rows.

import requests

params = {"make": "Ford", "page_size": 100, "sort": "price_asc"}
headers = {"Authorization": "Bearer hd_live_your_key_here"}

while True:
    resp = requests.get("https://luxe.hermesdata.io/v1_2/listings/search", params=params, headers=headers)
    resp.raise_for_status()          # 400 snapshot_expired -> restart the walk
    body = resp.json()

    for listing in body["data"]:
        print(listing["id"])

    cursor = body["meta"].get("next_cursor")
    if not cursor:                   # null on the last page
        break
    params["cursor"] = cursor        # keep the filters and sort - the token only says where to resume
    params.pop("page", None)         # page and cursor are mutually exclusive

Response headers

Every route, grouped. Each row expands to its full input contract - a typed parameter table - a runnable request in your language, and a real response body. Base URL https://luxe.hermesdata.io.

Recipes

6 end-to-end jobs. Each one is complete - paste it, swap your key, and it works.

import requests
from collections import defaultdict

BASE = "https://luxe.hermesdata.io/v1_2/listings"
H = {"Authorization": "Bearer hd_live_your_key_here"}

by_site, by_dealer = defaultdict(list), defaultdict(list)
params = {"state": "TX", "make": "Ford", "page_size": 100}

while True:
    body = requests.get(f"{BASE}/search", params=params, headers=H).json()
    for row in body["data"]:
        by_site[row["dealer_site_id"]].append(row["id"])
        dealer = row.get("dealer_id")          # ABSENT when unresolved
        if dealer:
            by_dealer[dealer].append(row["id"])
    cursor = body["meta"].get("next_cursor")
    if not cursor:
        break
    params = {**params, "cursor": cursor}

print(len(by_site), "websites,", len(by_dealer), "known dealerships")

# Filterable: dealer_id ANDs with every other search param.
curl "https://luxe.hermesdata.io/v1_2/listings/search?dealer_id=d_10c4f2&year_min=2024&sort=price_desc" \
  -H "Authorization: Bearer hd_live_your_key_here"

# Or the whole lot, unioned across every website the dealership runs.
curl "https://luxe.hermesdata.io/v1_2/listings/dealers/id/d_10c4f2/inventory?page_size=100" \
  -H "Authorization: Bearer hd_live_your_key_here"

# Neither errors on an id we can't place: the filter returns an empty result
# set, the inventory route returns 404 dealer_not_found.

import requests

BASE = "https://luxe.hermesdata.io/v1_2/listings"
H = {"Authorization": "Bearer hd_live_your_key_here"}

# site_ids collected from a day of search / recents rows
site_ids = sorted({row["dealer_site_id"] for row in todays_rows})

resolved = {}
for i in range(0, len(site_ids), 500):            # 500 is the per-call cap
    chunk = site_ids[i:i + 500]
    body = requests.post(f"{BASE}/dealers/resolve/batch",
                         json={"site_ids": chunk}, headers=H).json()
    for payload in body["data"]:                  # same order as the input
        resolved[payload["site_id"]] = payload

known = [p for p in resolved.values() if p["resolution"] != "unknown"]
print(f"{len(known)}/{len(site_ids)} sites tied to a dealership")

import requests

BASE = "https://luxe.hermesdata.io/v1_2/listings"
H = {"Authorization": "Bearer hd_live_your_key_here"}

cut = requests.get(f"{BASE}/search", headers=H, params={
    "state": "TX", "make": "Ford", "model": "F-150",
    "price_changed_within_days": 7,       # 1-90; 90 is the tracking retention
    "page_size": 100,
}).json()

for row in cut["data"]:
    if row.get("listing_status") != "active":
        continue                          # in the catalog, but not seen lately
    hist = requests.get(f"{BASE}/vehicles/{row['id']}/history", headers=H).json()
    drops = [e for e in hist["events"] if e["field"] == "sale_price"]
    if drops:
        first, last = drops[0], drops[-1]
        print(row["id"], first["old"], "->", last["new"], "over", len(drops), "moves")

import requests

BASE = "https://luxe.hermesdata.io/v1_2/listings"
H = {"Authorization": "Bearer hd_live_your_key_here"}

# Hot-column filters bind on ARCHIVED rows only, so this query deliberately
# excludes thin-only rows - that is the trade for filtering on make/model.
params = {"make": "Ford", "model": "F-150", "state": "TX",
          "sold_within_days": 30, "page_size": 100}

prices, thin = [], 0
while True:
    body = requests.get(f"{BASE}/sold/search", params=params, headers=H).json()
    for row in body["data"]:
        if row["status"] != "sold":       # unverified is NOT a sale
            continue
        if row["record_type"] == "lifecycle":
            thin += 1
            prices.append(row["last_price"])
        else:
            prices.append(row["sale_price"])
    cursor = body["meta"].get("next_cursor")
    if not cursor:
        break
    params = {**params, "cursor": cursor}

prices = sorted(p for p in prices if p)
print(len(prices), "sold comps,", thin, "of them thin,",
      "median", prices[len(prices) // 2])

import requests

VIN = "1FTFW1E84PFA12345"
car = requests.get(f"https://luxe.hermesdata.io/v1_2/listings/vehicles/{VIN}",
                   headers={"Authorization": "Bearer hd_live_your_key_here"}).json()

print("representative:", car["dealer_netloc"], car.get("sale_price"))

# Same dealership, its other websites.
for row in car["co_listings"]:
    print("  also at", row["dealer_netloc"], row["sale_price"])

# Other dealerships claiming this VIN. dealer_id is explicitly null here when
# the site is unresolved - claim entries are fixed-shape, unlike sparse cards.
for row in car["other_claimants"]:
    who = row["dealer_id"] or row["dealer_site_id"]
    print("  claimed by", who, "at", row["sale_price"])

Site ids in these examples (4c1f9a2e7b83d05614af2c9e3d70b8a1) are illustrative - real ones come off your own rows or from /dealers/resolve/….

Who is selling the car

Every listing was scraped from a website. That website is run by a dealership, and one dealership often runs several websites. So "who is selling this car" has two answers, and each listing carries both where we know them: the website it was published on (always), and the dealership behind that website (when we can match the two).

Worked example: four websites, three ways to group them

Example Ford runs two websites - its main one, plus an old domain that now just redirects. Example Kia is a separate dealership sharing the same lot, with its own website. And a fourth website belongs to a dealer we have no record for. Four websites, four site ids:

• Group by dealer_site_id and you get four buckets - one per website.
• Group by dealer_id and you get one bucket per dealership - two here. The redirect domain has no dealership of its own, so it drops out. Group by entity_dealer_id and the first three collapse into one bucket, because Example Ford and Example Kia sit on the same lot and count as one business. The fourth website has neither key, so group it by its site id.
• Resolving either of the first two names the other in its sibling_site_ids (capped at 50).
• Inventory by dealer id serves one storefront - /dealers/id/d_10c4f2/inventory - while inventory by entity id serves the whole campus as one paged result set: /dealers/entity/d_10c4f2/inventory.

Stability: what's safe to store

While identity is warming up

The dealer-resolution map loads asynchronously after a deploy. v1.2 keeps serving throughout - nothing 503s and no shape changes - but the dealership half of identity is briefly missing. Build for this column and you are also built for websites we simply can't place:

Sold cars & price history

When a car comes off the market we keep its record for about 90 days, along with every price and odometer change we saw while it was listed. Two things follow. A VIN or id that no longer matches a car for sale still returns something instead of a 404, and you can ask what a car did - what it listed at, what it dropped to, whether it sold - not only what it costs today.

Three states, three different claims

One key, three pools

A lookup by id or VIN checks three places in order - the live catalog, then the 90-day archive, then a last-resort index that holds only status and dates - and answers from the first one that has the record. Same route, same keyed charge - different body shapes, told apart by record_type:

// The SAME key that answered live above, after the car sold. Card route:
{
  "record_type": "sold",
  "status": "sold",
  "sold_date": "2026-08-29",
  "id": "v_9f3a21",
  "vin": "1FTFW1E84PFA12345",
  "make_name": "Ford",
  "model_name": "F-150",
  "year": 2024,
  "sale_price": 58995,
  "dealer_netloc": "exampleford.com",
  "dealer_site_id": "4c1f9a2e7b83d05614af2c9e3d70b8a1",
  "dealer_id": "d_10c4f2",
  "entity_dealer_id": "d_10c4f2",
  "first_seen": "2026-07-19",
  "last_seen": "2026-08-27"
}

// And an id we never captured a full row for - the thin body, all we have:
{
  "record_type": "lifecycle",
  "id": "v_51ba07",
  "vin": null,
  "status": "unverified",
  "sold_date": null,
  "first_seen": "2026-06-30",
  "last_seen": "2026-08-02",
  "days_listed": 33,
  "last_price": 24990,
  "source": "northsideauto.example",
  "listing_cycle": 1,
  "is_current": true
}
// Live always wins: a relisted id answers with its live card even while the
// archive still holds the old sale. So a 404 vehicle_not_found now means "never
// seen inside the window", not "not for sale today".
//
// Archived sold cards ARE dealer-enriched on the v1.2 keyed routes. Thin bodies
// are not - there is no netloc-bearing card to enrich, only a source string.
// Neither shape ever carries claim groups.

Rules worth reading once

What's new in v1.2

Only relevant if you already have code on v1. If this is your first read, skip it.

Data schema

Every listing route returns a card - the fields below, grouped by topic. Only fields with a value appear, and id is always there.

Records inside the 90-day window

What /sold/search pages and what a keyed lookup falls through to. Two shapes on one page - read record_type first.

History body

Returned by /vehicles/{key}/history. Fixed shape with explicit nulls - every field is always there.

Errors

Every error shares one envelope. Branch on code - it's stable; the message is for humans and may change. Some 400s add a details[] array pinpointing the offending parameter. On 429 and 503, wait for the Retry-After header before retrying. v1.2 introduces no new error codes.

{
  "error": true,
  "code": "invalid_range",
  "message": "year_min must be ≤ year_max.",
  "details": [
    { "field": "year_min", "issue": "greater than year_max" }
  ]
}

One exception: a request that times out returns a plain 408 with no JSON body - treat any 408 as a timeout.

• 402 spend_frozen carries a reason of payment_dispute or past_due. Buying credits does not clear it - resolve the billing hold on your account.
• An unknown site_id or dealer_id is not an error on search (empty result set) or on resolve (resolution: "unknown"). It is a 404 dealer_not_found on the inventory routes, which need a real target.

Metering & credits

No subscription - each request costs a little from one shared credit wallet, based on the kind of request. Because a single call costs far less than a whole credit, prices here are quoted in millicredits (mc): 1,000 mc = 1 credit. So a 10 mc search page is a hundredth of a credit. Your wallet and your invoices only ever show whole credits. Run out and you get 402 insufficient_credits. The current price for each kind of request is always live at GET /v1_2/listings/meta - read it from there rather than hard-coding.

Note: a batch lookup is priced per id - each id is one keyed charge - and any 4xx/5xx error is refunded, so failed calls never cost credits. Two safety limits apply: 100 requests/second per key and a spend ceiling of 120 credits/minute, each returning 429 with a Retry-After.

v1.2 costs the same as v1. Every mirrored route bills exactly what its /v1 twin bills - dealer identity on a row is free. The three new dealer routes bill at the scan class, the same as dealer inventory, and resolve/batch is one scan charge per request however many of its 500 site ids you use.

Pricing

One shared wallet, no subscription - you're billed per API call by request type, and errors are never charged. Roughly 10,000 listings per credit when you page search; full records, lookups, and stats meter differently:

Need the whole file instead?