Documentation

Overview

Vehicle Listings is a read-only REST API for live vehicle inventory across the US & Canada. Every listing is tied to the dealership selling it. Search and filter the catalog, look up a vehicle by id or VIN, or pull market stats. v1.2 adds the dealer layer: every row names the website it came from and, where we can place it, the dealership entity behind it.

Dealer identity

A listing is published on a website. A website belongs to a dealership, and a dealership often runs several websites. v1.2 hands you both levels: the website is always identified, and the dealership is identified whenever we can tie the two together.

Worked example: one dealership, two websites

Example Ford runs two sites for one physical rooftop, and a third site in the same market is a dealer we hold no record for. Three websites, three site ids, one dealership:

• Group by dealer_site_id and you get four buckets - one per website.
• Group by dealer_id and you get one bucket per dealership. The old domain has no dealership of its own - it only redirects - so it drops out. Group by entity_dealer_id instead and the first three collapse into one business, because the Kia store shares the Ford store's lot. The stranger has neither key, so fall back to 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:

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

List routes take page (1-based) and page_size (1–1000, default 25), and report meta.total - the full match count across the catalog. A page_size over 1000 is clamped silently and echoed back at 1000, so read the echo rather than assuming your value was honoured.

A scan call bills one charge per started 100 rows returned: 1 and 100 rows both cost one charge, 250 rows cost three, 1000 rows cost ten. Same per-row price at any page_size, so a wide page saves round trips, not credits. A short page is billed on what arrived.

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

Quickstart

Grab your key from the API key page and make your first call against live data. It searches the catalog and returns matching listings in a { data, meta } wrapper:

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.

There is no separate sandbox - you call live data, metered per API call by request type. A keyed lookup by id or VIN is the smallest charge, and paging search results runs about 10,000 listings per credit. From here, browse the full API reference or see every field in the data schema.

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

Four 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

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/….

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.

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