# TheCarApi — full content
Generated 2026-08-24. Canonical site: https://thecarapi.com
---
# SEO for inventory-driven sites: what changes when AI crawlers cannot run JavaScript
URL: https://thecarapi.com/blog/seo-for-data-driven-sites
Published: 2026-08-05 · Updated: 2026-08-07
Category: Guides
Google renders JavaScript, eventually. GPTBot, ClaudeBot and PerplexityBot do not render it at all — which changes the calculation for any site whose content is its inventory.
Inventory-driven sites — vehicle marketplaces, property portals, anything where the catalogue is the content — get most of their traffic from organic search. They are also, disproportionately, built as client-rendered single-page applications, because that is what the frontend tooling makes easy.
Those two facts are in direct conflict, and the conflict got sharper when AI crawlers became a meaningful discovery channel. This is what the problem actually looks like and what to do about it.
## What a crawler sees
A client-rendered SPA serves every URL the same HTML document:
```html
Cars — Marketplace
```
Identical for the homepage, for every category page, and for all 200,000 listing URLs. Same title, no description, no canonical, no content.
Google will render the JavaScript and eventually see the real page. But rendering happens in a second pass, on a separate queue, and crawl budget is allocated from the first. What Googlebot sees on pass one is a large number of URLs with an identical title and no text — which is, structurally, the profile of a low-quality auto-generated site. On a site whose whole proposition rests on being trusted, that is a bad first impression to make at scale.
> **AI crawlers do not render at all** — The crawlers behind AI answers and citations generally fetch HTML and read it. They do not execute your bundle. A client-rendered site is not partially visible to them — it is a blank page. If being the source an AI answer cites has any value to you, that is the whole channel gone.
## The fix, in order of impact
### 1. Real URLs and real anchors
Prerequisite for everything else, and frequently the missing piece. If navigation is ``, there is nothing to crawl and nothing to link to — no amount of meta-tag work helps a site with one URL.
Every page needs its own path, and every navigation control needs to be an `` that a crawler can follow and a user can middle-click. Intercept the click for client-side routing if you want the SPA feel; keep the anchor.
### 2. Prerender the pages you can enumerate
Marketing pages, documentation, articles, category pages — anything with a known, bounded URL list — should be rendered to static HTML at build time. For a React app this is not a rewrite: render each route with `renderToString`, inject the result and the per-page head into the built HTML template, and hydrate on the client.
You get complete HTML for crawlers, a faster first paint for users, and no framework migration.
### 3. Server-render the head for pages you cannot enumerate
Individual listing pages are the hard case: there can be hundreds of thousands, they change constantly, and prerendering all of them at build time is not viable. The pragmatic answer is to inject the head server-side per request — title, description, canonical, OG tags and structured data — from a single database lookup, while leaving the body to the client.
It is perhaps sixty lines of string replacement on the HTML template, and it converts a mass of identical shells into individually described pages.
```html
2021 Kia Niro 1.6 GDi HEV, 77,205 km — auction lot | Example
`, `` for sections, in order. Headings styled with a div and a font size are invisible as structure.
- **Put comparative data in tables.** A genuine ` ` extracts cleanly; a grid of divs does not.
- **State dates and figures explicitly.** "As of August 2026" is usable; "recently" is not.
- **Be specific about uncertainty.** "Terms vary by country — verify with the platform" is more useful to an extraction system than false confidence, and it is more honest to your readers.
### Machine-readable mirrors
An emerging convention worth adopting: publish `/llms.txt` — a plain-text map of your site for language models — and serve Markdown versions of your articles alongside the HTML. It costs almost nothing if your content is structured rather than stored as HTML strings, and it removes any ambiguity about what your pages say.
## Decide the AI crawler question deliberately
Many sites now block AI crawlers, often by accepting a CDN default rather than by making a decision. The distinction that matters is between two different kinds of bot:
| Type | Examples | What blocking costs you |
| --- | --- | --- |
| Search / citation crawlers | OAI-SearchBot, ChatGPT-User, PerplexityBot, Claude-SearchBot | Your site can never be cited in an AI answer. This is a real discovery channel. |
| Training harvesters | CCBot, Bytespider, and similar | Little, in most cases. Blocking these is a defensible default. |
Blocking everything removes the upside while keeping all the downside. Worth noting too that blocking `Google-Extended` does not affect Google Search or AI Overviews, which run on standard Googlebot — so it is a lower-stakes setting than it is often assumed to be.
Whatever you choose, check what is actually being served. CDN-managed rules frequently prepend directives to `robots.txt` and apply firewall rules above it, so the file in your repository may not be the file the crawler receives. Verify with a request carrying the relevant user agent.
## An audit worth running
Ten minutes, and it finds most of what is wrong:
1. `curl` a category page and a listing page. Is there content in the HTML, or an empty div?
2. Do the two pages have different titles and descriptions?
3. Is there a canonical, and does it point where you expect?
4. Do your navigation links appear as `` in the raw HTML?
5. How many URLs are in your sitemap, and what fraction render real content?
6. What does `robots.txt` return over the network, not in your repository?
7. Do sold or expired items still return HTTP 200 with a shell?
8. Are filtered URL variants indexable and competing with clean ones?
If the first question fails, the rest do not matter yet — start with prerendering. [Building a marketplace](/blog/build-used-car-marketplace) covers where this sits in the wider architecture.
### FAQ
**Do AI crawlers execute JavaScript?**
Generally not. The crawlers behind AI answers and citations fetch HTML and read it directly rather than running your bundle. A client-rendered single-page application therefore appears to them as an empty page, not a partially loaded one — so the entire AI citation channel is unavailable regardless of how good the content is.
**Is client-side rendering bad for Google specifically?**
Google does render JavaScript, but in a second pass on a separate queue, while crawl budget is allocated from the first pass. At scale that means large numbers of URLs sharing one title with no text on initial crawl — which resembles a low-quality auto-generated site and wastes budget that could go to pages capable of ranking.
**How do I add SEO to an existing React SPA without rewriting it?**
Add real URLs and real anchor tags first, then prerender the enumerable routes at build time by rendering each with renderToString and injecting the output plus a per-page head into the built HTML template, hydrating on the client. For unbounded listing URLs, inject just the head server-side per request from a single database lookup. Neither step requires a framework migration.
**Should I put every listing URL in my sitemap?**
No. Filter to listings worth landing on — live, photographed, with a resolved make and model — and remove sold or expired items rather than leaving them indefinitely. Make sure the sitemap and your meta robots tags use the same threshold, since submitting URLs you are simultaneously telling Google to ignore is a contradiction that wastes crawl budget.
**Should I block AI crawlers in robots.txt?**
Distinguish the two kinds. Blocking pure training harvesters is a defensible default. Blocking search and citation crawlers means your site can never be the source an AI answer cites, which is a real discovery channel — so blocking everything removes the upside while keeping the downside. Also verify what is actually served, since CDN-managed rules often override the file in your repository.
**What is llms.txt?**
An emerging convention: a plain-text file at the root of a site that maps its content for language models, often paired with Markdown versions of pages served alongside the HTML. It is inexpensive to generate if your content is stored as structured data rather than HTML strings, and it removes ambiguity about what your pages actually say.
---
# Integrating a vehicle auction API: pagination, caching, retries and rate limits
URL: https://thecarapi.com/blog/auction-api-integration-guide
Published: 2026-07-30 · Updated: 2026-08-07
Category: Guides
The first integration always works. The one that survives a traffic spike, a source outage and a schema change is a different piece of software.
This is the article to read after you have made your first successful call and before you put anything in front of users. Everything below comes from integrations that broke in a specific, avoidable way.
## Authentication and key handling
Keys go in a header, never in a query string — query strings end up in access logs, browser history, referrer headers and error trackers.
```bash
# Either form works
curl -H "X-API-Key: $API_KEY" "https://api.thecarapi.com/api/search?limit=1"
curl -H "Authorization: Bearer $API_KEY" "https://api.thecarapi.com/api/search?limit=1"
```
> **Never call the API from the browser** — A key shipped to the client is a public key, whatever your intentions. Proxy through your own backend, which also gives you a place to cache, rate-limit your own users, and swap providers without a frontend release.
One operational detail worth knowing before it bites: repeated authentication failures typically trigger lockouts. A misconfigured staging environment hammering the API with a stale key can lock out the IP that production shares. Keep environments on separate keys and fail fast on a 401 rather than retrying it.
## Cache by data type, not by endpoint
The single highest-leverage decision in the whole integration. The four data layers change at completely different rates, and one TTL across all of them is either far too aggressive or far too conservative.
| Data | Suggested TTL | Reasoning |
| --- | --- | --- |
| Catalog — brands, models, fuels, countries | **24 hours** | Changes when a new nameplate appears. Cache hard. |
| Facet counts | 5 – 15 minutes | Approximate by nature; nobody notices a slightly stale count. |
| Search results | 1 – 5 minutes | Balances freshness against repeated identical queries. |
| Vehicle detail (specification) | 1 hour | Specification does not change. Price does — see below. |
| Current price / bid | **Do not cache** | A cached live price is a wrong price. |
| Image galleries | Days | Effectively immutable once the lot is listed. |
| Price history | 15 minutes | Append-only; staleness only costs you the newest point. |
The detail row deserves care. Specification and price arrive in the same payload but have opposite requirements. The clean resolution is to cache the detail response for the specification fields and re-read price separately on any screen where the user might act on it.
Many GET endpoints are already cached at the edge and return an `X-Cache` header. Log it — an unexpectedly low hit rate usually means you are varying a parameter you did not intend to, such as passing a timestamp or an unstable sort into an otherwise identical query.
## Pagination without falling off the end
Three rules that cover almost every pagination problem in this domain.
### Skip the count when you do not need it
Counting matching rows across a large filtered set is frequently the most expensive part of a search. On infinite scroll or a "load more" pattern you never display the total, so pass `include_total=false` and drop the cost entirely.
### Respect the depth limit
Deep offsets are expensive everywhere, and most APIs cap them. If you need to walk an entire result set — for a nightly reconciliation, say — do not page to offset 50,000. Partition the query instead: iterate by brand, or by year, or by price band, keeping each partition shallow.
```python
# Wrong: falls off the depth limit and gets slower every page
offset = 0
while True:
page = search(brand="bmw", offset=offset, limit=100)
if not page["results"]:
break
offset += 100
# Right: partition so every query stays shallow
for year in range(2015, 2027):
offset = 0
while True:
page = search(brand="bmw", year_from=year, year_to=year,
offset=offset, limit=100, include_total=False)
if not page["results"]:
break
yield from page["results"]
offset += 100
```
### Seed your random sorts
If you sort randomly for variety, the ordering must be stable across pages or page two will repeat rows from page one. The search response returns a `random_seed`; pass it back on subsequent pages.
## Retries, and what not to retry
A retry policy that retries the wrong things turns a small problem into an outage. The rule is: retry only what could plausibly succeed next time.
| Status | Retry? | How |
| --- | --- | --- |
| `429` rate limited | Yes | Honour `Retry-After` if present, otherwise exponential backoff with jitter |
| `500` / `502` / `503` / `504` | Yes | Exponential backoff, cap at 3–4 attempts |
| `408` timeout | Yes | Once, then narrow the query — often a filter is too broad |
| `401` / `403` | **No** | The key is wrong. Retrying triggers lockout protection |
| `400` bad request | **No** | A malformed query will stay malformed |
| `404` | **No** | The lot does not exist, or has been removed |
Use jitter. Without it, every client that failed during a brief outage retries at the same instant and produces a thundering herd on recovery — turning a thirty-second blip into a sustained incident.
```javascript
const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
async function call(url, { attempts = 4 } = {}) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, { headers: { 'X-API-Key': process.env.API_KEY } });
if (res.ok) return res.json();
if (!RETRYABLE.has(res.status)) {
throw new Error(`${res.status} ${await res.text()}`); // fail fast, do not retry
}
const after = Number(res.headers.get('retry-after')) * 1000;
const backoff = after || 2 ** i * 250 + Math.random() * 250; // jitter
await new Promise(r => setTimeout(r, backoff));
}
throw new Error('exhausted retries');
}
```
## Log the request id
Responses carry a request id, also returned as `X-Request-ID`. Log it with every call, and surface it in your own error messages. It converts a support conversation from "search was slow this morning" into a specific call someone can look up. This costs one line and is the highest-value logging you will add.
Log `contract_version` too. When a response shape changes, the version in your logs tells you exactly when, which is otherwise a genuinely difficult thing to reconstruct.
## Handle sparse fields properly
Fields are present when the source provides them, which means absent fields are the normal case rather than an error. Two habits:
- **Never assume a field exists.** VIN, horsepower, photo count and equipment lists are all commonly absent. Destructuring without a default is the most common cause of a crash in a vehicle frontend.
- **Distinguish null from zero.** A mileage of `0` means the odometer read zero. `null` means the source did not say. Rendering both as "0 km" makes every unknown-mileage car look new.
> **Monitor fill rates, not just errors** — A field that was 95% populated and drops to 40% is a broken upstream extractor, and it will not raise a single error in your logs. Track fill rate per field per source over time — it catches an entire class of silent data degradation that error monitoring is blind to.
## Health checks and graceful degradation
A vehicle marketplace does not need to go down because one endpoint is slow. Decide in advance what degrades and how:
1. If **images** fail, render cards with a placeholder. Do not fail the page.
2. If **facets** fail, render search without filter counts. Users can still search.
3. If **price history** fails, hide the chart. It is an enhancement, not the product.
4. If **search** fails, that is a real outage — surface it honestly rather than showing an empty result set, which users read as "no cars match" and act on.
That last distinction matters more than it looks. An empty result set and a failed request are completely different messages to a user, and conflating them makes your product look like it has no inventory.
```bash
curl -s "https://api.thecarapi.com/api/health"
```
_Cheap to poll, and worth wiring into your own status page rather than discovering an issue from users._
## A pre-launch checklist
- API key is server-side only, and staging uses a different key from production.
- Cache TTLs are set per data type; live prices are not cached.
- Retries cover only retryable statuses, with jitter and an attempt cap.
- `include_total=false` on any view that does not display a count.
- Deep pagination is partitioned rather than offset-walked.
- Request ids are logged and surfaced in errors.
- Every field access tolerates absence; null and zero are distinguished.
- Degradation behaviour is defined per endpoint, and empty results are visibly distinct from failures.
- Fill-rate monitoring is running before launch, not after the first data incident.
Endpoint-level detail for everything referenced here is in [the API reference](/docs), and [building a marketplace](/blog/build-used-car-marketplace) covers the architecture these mechanics sit inside.
### FAQ
**How long should I cache vehicle auction API responses?**
By data type rather than by endpoint. Catalog values such as brands and fuels can cache for 24 hours; facet counts 5–15 minutes; search results 1–5 minutes; vehicle specification around an hour; image galleries for days. Current prices and bids should not be cached at all — a cached live price is simply a wrong price.
**Which HTTP errors should I retry?**
Retry 408, 429 and 5xx with exponential backoff and jitter, capped at three or four attempts, honouring Retry-After when present. Never retry 400, 401, 403 or 404 — those will not succeed on a second attempt, and repeatedly retrying authentication failures can trigger lockout protection that affects your whole environment.
**How do I export a large result set without hitting pagination limits?**
Partition the query instead of walking deep offsets. Iterate over brands, years or price bands so each individual query stays shallow, and pass include_total=false since you are not displaying a count. Deep offsets get progressively more expensive and are usually capped, so an offset-walk over tens of thousands of rows will fail or time out.
**Can I call the auction API directly from my frontend?**
No. Any key shipped to a browser is public regardless of intent. Proxy through your own backend, which also gives you a natural place to cache responses, apply your own per-user rate limiting, and change providers without shipping a frontend release.
**Why do fields sometimes disappear from responses?**
Fields are present when the source publishes them, so absence is normal rather than exceptional — VIN, horsepower and equipment lists are frequently missing. A sudden drop in how often a field appears, though, usually indicates a broken upstream extractor. That produces no errors, so it is only caught by monitoring fill rate per field per source over time.
---
# Building a used car marketplace without owning inventory
URL: https://thecarapi.com/blog/build-used-car-marketplace
Published: 2026-07-21 · Updated: 2026-08-07
Category: Guides
The hard part of a marketplace is never the listings page. It is having something to list on day one, and having a reason for anyone to use you rather than the source.
Every marketplace starts empty, and an empty marketplace has no reason for anyone to visit, which means no sellers, which means it stays empty. In most categories you break that loop with sales effort. In vehicles you can sidestep it, because wholesale inventory already exists in volume and is reachable programmatically.
That solves the cold start and immediately creates the real question: if your listings come from the same feed anyone can license, what makes your product worth using? This walks through both — the architecture, and the part that has to be yours.
## Decide what you actually are
Four viable shapes, with materially different technical requirements. Choosing late is expensive.
| Model | You provide | Revenue | Hardest part |
| --- | --- | --- | --- |
| Discovery portal | Search and comparison, referral out | Referral or subscription | Traffic acquisition |
| Brokerage | Search plus you transact on the buyer's behalf | Commission per deal | Operations, trust, logistics |
| Dealer tooling | Sourcing and pricing for trade buyers | SaaS subscription | Beating a spreadsheet |
| Regional importer | Curated foreign stock, landed prices in local currency | Margin per vehicle | Import compliance |
The discovery portal is the easiest to build and the hardest to sustain, because you are competing on SEO against the sources themselves. The regional importer is the opposite: real operational work, but a genuine reason to exist, because the buyer cannot access German or Korean wholesale supply directly and does not want to handle the import.
## The data layer
The decision that shapes everything downstream: proxy the API on every request, or maintain your own copy?
### Proxy-through
Your backend forwards search requests to the provider and returns the response. Nothing is stored. It is fast to build and always fresh, and it is the right starting point.
It stops working when you need to join provider data against your own — favourites, sold-by-you flags, custom pricing, per-vehicle notes — or when your traffic makes per-request calls expensive, or when you need search behaviour the provider does not offer.
### Local mirror
You sync inventory into your own database and search it locally. More moving parts, and it introduces a staleness window you now own — but it lets you rank, join and enrich freely.
> **The pragmatic middle** — Mirror the search-card fields you need for listing and filtering. Fetch detail, images and price history live on demand. You get local ranking and joins without duplicating the heavy, fast-changing parts — and your staleness exposure is limited to a small, well-understood field set.
Whichever you choose, key everything on the source pair. Your favourites table stores `openlane/11125938`, not a synthetic id that will not survive a resync.
```sql
create table saved_vehicle (
id bigserial primary key,
user_id bigint not null references app_user(id),
site_name text not null, -- openlane | auto1 | encar | ...
auction_id text not null, -- the platform's own lot id
saved_at timestamptz not null default now(),
-- denormalized so a saved list still renders after the lot closes
title_snapshot text,
price_eur_snapshot numeric(12,2),
unique (user_id, site_name, auction_id)
);
```
_Snapshotting title and price is not redundancy — it is what stops a user's saved list turning into a page of dead references once lots close._
## Search is your product
Users judge a vehicle marketplace almost entirely on search. Four things carry most of the perceived quality:
1. **Facet counts that are live.** A filter option showing zero results, or showing results that do not exist, destroys trust faster than any other defect. Drive facets from the API rather than a static list.
2. **Sensible defaults.** Newest-first or best-value-first beats a raw price sort, which surfaces the least desirable stock at the top of every page.
3. **Fast pagination.** Counting total matches is often the most expensive part of a search. On infinite scroll, request `include_total=false` and skip it.
4. **Stable ordering under randomisation.** If you shuffle results for variety, use a seed so page two does not repeat page one.
```bash
# Page 1 — note the returned random_seed
curl -s "https://api.thecarapi.com/api/search?sort=random&limit=24&include_total=false" \
-H "X-API-Key: $API_KEY"
# Page 2 — pass the seed back so the ordering stays consistent
curl -s "https://api.thecarapi.com/api/search?sort=random&seed=k9f2ab\
&limit=24&offset=24&include_total=false" \
-H "X-API-Key: $API_KEY"
```
Build the filter UI from [the catalog endpoints](/docs/catalog) rather than hardcoding brand and fuel lists. Source vocabularies drift, and a hardcoded value that changes upstream fails silently as an empty result set — the worst kind of bug, because it looks like a market condition.
## Images decide how the product feels
Rules that matter more here than in most product categories, because the listing grid is the product:
- Thumbnail only on search cards. Never fetch galleries for a results page.
- Set explicit width and height so the grid does not reflow as images arrive.
- `loading="lazy"` below the fold; eager for the first row.
- Generate alt text from the vehicle data you already have — it is free accessibility and free image SEO.
- Never hotlink source URLs. [They expire and are hotlink-protected](/blog/vehicle-image-cdn-api), and the failure is delayed enough to reach production.
## The part that has to be yours
If your entire product is a nicer frontend over a feed, your competitive position is a design refresh away from disappearing. The defensible layer is always something the feed cannot contain:
- **Landed cost in the buyer's currency and jurisdiction.** Transport, duty, VAT, registration, your fee — one number a buyer can act on. Genuinely hard, genuinely valuable, and specific to a market you understand.
- **Curation.** Rejecting 95% of available stock is a service. "Every car in Europe" is not a value proposition; "the forty cars worth your attention this week" is.
- **Trust infrastructure.** Escrow, inspection, delivery, a real company with a real address. This is the entire product for cross-border buyers.
- **A proprietary signal.** Your own repair-cost model, your own local demand data, your own dealer network's bid history.
- **Workflow.** For trade buyers, integration into how they actually work — CRM, stock management, alerts on saved searches — beats a better search box.
> Nobody wins a market by showing the same listings as everyone else, slightly later. The feed is the floor you build on, not the building.
## A launch sequence
1. **Week 1** — proxy search and detail straight through. No database, no auth. Prove the funnel: do people search, and do they click?
2. **Week 2–3** — accounts, saved vehicles, saved searches. This is the first thing that makes returning worthwhile.
3. **Week 4–6** — the mirror, if search performance or joins demand it. Not before.
4. **Week 6+** — the defensible layer. Landed cost, curation, or whichever of the above fits your market.
5. **Continuously** — SEO. Vehicle marketplaces live on organic search, and that means server-rendered listing pages with real URLs, not a client-only app. [See how we handle it](/blog/seo-for-data-driven-sites).
> **Do not build the mirror first** — The most common failure is spending six weeks on sync infrastructure before finding out whether anyone wants the product. Proxy-through gets you a testable marketplace in days. Add the database when a specific limitation forces it — and it will tell you clearly when it does.
For the integration mechanics — pagination, caching, retries, rate limits — [the integration guide](/blog/auction-api-integration-guide) covers the details, and [the API reference](/docs) documents every endpoint used here.
### FAQ
**Can I build a car marketplace without owning any vehicles?**
Yes — it is the standard way to solve the cold-start problem in this category, because wholesale inventory already exists in volume and is reachable programmatically. The consequence is that inventory stops being a differentiator, so the product needs something the feed cannot supply: landed cost, curation, trust infrastructure, or workflow integration.
**Should I mirror the inventory into my own database or proxy the API?**
Start by proxying — it is faster to build, always fresh, and lets you validate the product in days. Move to a mirror only when a specific need forces it: joining against your own data, ranking the provider does not offer, or per-request cost at your traffic level. A common middle ground is mirroring search-card fields while fetching detail and images live.
**What should I use as the primary key for vehicles?**
The source platform slug together with the platform's own lot id — for example `openlane/11125938`. It is stable, survives resyncs, and is what every detail, image and price-history endpoint is addressed by. Also snapshot the title and price in tables like saved vehicles, so a user's list still renders after the underlying lot closes.
**How do I compete with the auction platforms themselves?**
Not on inventory, since it is the same stock. Compete on something the source cannot offer: landed cost in the buyer's currency and jurisdiction, curation that rejects most of the catalogue, trust infrastructure for cross-border purchases, or workflow integration for trade buyers. Access to supply the buyer cannot reach directly is itself the value in the importer model.
**What is the most common mistake when launching one of these?**
Building sync infrastructure before validating demand. Teams spend six weeks on a mirror, ranking and caching before learning whether anyone wants the product. Proxying the API directly gets a testable marketplace live in days, and the limitations that justify a database announce themselves clearly when they arrive.
---
# Used car market value: wholesale prices, retail asking prices, and the spread
URL: https://thecarapi.com/blog/used-car-market-value-comparables
Published: 2026-07-08 · Updated: 2026-08-07
Category: Market intelligence
The gap between what the trade pays and what the market asks is where every margin in this industry lives. Measuring it correctly requires two datasets that must not be merged.
"What is this car worth?" is not one question. It is at least four, with genuinely different answers, and a valuation product that does not say which one it is answering will produce numbers that are individually defensible and collectively incoherent.
| Question | Answer comes from | Typical relationship |
| --- | --- | --- |
| What will the trade pay at auction? | Auction clearing prices | The floor |
| What is it listed for retail? | Classifieds asking prices | The ceiling — an aspiration |
| What does it actually retail for? | Asking price minus negotiation | Below the ceiling, by a variable amount |
| What will it cost me landed? | Hammer + fees + transport + duty + VAT | Above the floor, sometimes far above |
Confusing the first and second is the most common error, and it is expensive in both directions: it makes auction stock look like a bargain to a buyer, and makes a dealer's margin look larger than it is.
## Why asking prices are not transaction prices
Classifieds data is abundant and easy to collect, which is exactly why it is over-trusted. An asking price is a seller's opening position, and four biases sit between it and reality:
- **Negotiation.** Most private and many dealer sales close below the advertised figure. The discount varies by market, by model and by how motivated the seller is.
- **Survivorship, running backwards.** The ads you can see today are disproportionately the ones that have not sold. Well-priced cars leave the dataset quickly; overpriced ones accumulate in it. A naive average of live ads is therefore biased upward.
- **Listing age.** A three-day-old ad and a ninety-day-old ad at the same price are telling you completely different things about that price.
- **Presentation premium.** Retail prices include reconditioning, warranty, preparation and a physical location. None of that is in a wholesale figure, so the spread is not pure margin.
> **The survivorship bias is the one that gets missed** — It is counter-intuitive because it runs the opposite way to the familiar version. Fast-selling cars disappear from the visible set, so the live-ads average drifts upward over time even in a flat market. Weighting by listing age is a partial correction; treating asking prices as transaction prices is not.
## Keeping the two datasets apart
It is tempting to merge auction lots and classifieds into one searchable index. It produces a search result nobody can act on: a user filtering for cars under €10,000 gets a mixture of things they can bid on and things they can buy, at prices computed on incompatible bases, with no indication of which is which.
We keep them structurally separate for that reason — auction sources are one surface, [European retail classifieds](/docs/theparking) are another, and they are never merged into the same search. The classifieds data exists to answer "what does this retail for", not to pad the inventory count.
```bash
# Wholesale: what the trade is paying
curl -s "https://api.thecarapi.com/api/search?brand=bmw&model=320d\
&year_from=2019&year_to=2021&limit=50" \
-H "X-API-Key: $API_KEY"
# Retail: what the same car is asked for, across European portals
curl -s "https://api.thecarapi.com/api/theparking/listings?brand=BMW\
&country=de,at,nl&price_to=30000" \
-H "X-API-Key: $API_KEY"
```
_Two endpoints, two datasets, two meanings. The comparison is yours to make deliberately._
## Constructing a defensible reference price
A method that survives being questioned by someone with money at stake:
1. **Define the comparable set narrowly.** Same make, model, registration year, fuel, gearbox and damage state. Mileage within a proportional band — ±15% rather than a fixed kilometre figure.
2. **Prefer clearing prices to live observations.** A closed sale is a fact. A live asking price is a proposal.
3. **Adjust for mileage explicitly** rather than pooling. State the adjustment so it can be checked.
4. **Bound the recency window** to 60–90 days. Older data averages across a market that has moved.
5. **Report the sample size.** An estimate from four observations and one from four hundred must not be presented identically.
6. **Report the dispersion, not just the centre.** A tight cluster and a bimodal spread with the same median mean very different things about confidence.
The last two are what separate a reference price from a guess with a decimal point. A user who can see that the estimate rests on six cars with a wide spread will treat it appropriately; one shown a bare number will not.
```json
{
"auction_id": 11125938,
"site_name": "openlane",
"public_price_eur": 9800,
"market_reference": {
"price_eur": 12400,
"mileage": 71000,
"km_difference": -6205,
"explanation": "Reference from comparable listings, adjusted for mileage difference"
}
}
```
_Returned by `/api/top-offers`. The reference travels with the lot, so a user who disagrees with the signal can see what it was based on._
## Reading the spread
Once you have both numbers for the same vehicle, the ratio between them is more informative than either alone — but it needs interpreting, because a wide spread has several possible causes:
- **Genuine margin.** Real, and the basis of the trade.
- **Reconditioning cost.** The retail car has had work the auction car has not. Not margin.
- **Time cost.** Weeks of holding, financing and forecourt space between the two prices.
- **Condition difference the data does not capture.** The most likely explanation for an outlier, and the most dangerous to ignore.
- **Market segment mismatch.** A wholesale lot compared against a retail listing for a slightly different trim.
A practical heuristic: an apparent spread far above the norm for that model is more often a data problem than an opportunity. Investigate the comparable set before acting on it.
## Regional variation is signal, not noise
The same car does not cost the same across Europe, and the differences are systematic rather than random — driven by local taxation, emissions rules, fuel-type preference, climate and fleet composition. Diesel demand varies sharply between markets. Some countries apply registration taxes that make certain vehicles structurally more expensive.
For a valuation product this means a single European reference price is usually the wrong abstraction. Compute per-market references where you have the sample size, and be explicit about which market a number refers to. For a sourcing product, the variation is the whole opportunity.
> **Cross-border comparison needs landed cost** — A car cheaper in one country is only cheaper after transport, registration and — for non-EU sources — duty and import VAT. Comparing raw prices across borders without landed cost produces arbitrage that evaporates on contact with reality. See [the calculator endpoints](/docs/calculator).
## What to build first
If you are adding valuation to an existing product, the order that delivers value soonest:
1. A comparable set with the sample size shown. Even without a modelled price, showing a user the ten most similar recent sales is immediately useful and hard to argue with.
2. A mileage-adjusted reference price on top of that set.
3. The retail spread, once you have retail data for the same models.
4. Per-market breakdowns, once your sample supports splitting.
5. Trend over time, which requires the archive — and which is the reason [price history](/blog/car-price-history-api) needs to be collected before you need it.
### FAQ
**What is the difference between wholesale and retail used car prices?**
Wholesale is what the trade pays at auction — a transaction price between professionals. Retail asking price is what a seller advertises to a consumer, and it includes reconditioning, warranty, preparation and premises, as well as room to negotiate. They measure different things and should never be pooled into a single average.
**Why are classifieds asking prices biased upward?**
Survivorship, running in the unfamiliar direction. Well-priced cars sell quickly and leave the visible set, while overpriced ones remain and accumulate. An average of currently-live advertisements therefore drifts above the true transaction level even in a flat market. Weighting by listing age partially corrects for it.
**How many comparable vehicles do you need for a reliable price estimate?**
There is no single threshold, which is why the sample size should be shown rather than hidden. An estimate from four observations and one from four hundred are both legitimate outputs but carry completely different confidence, and presenting them identically misleads the user. Report dispersion alongside the central figure.
**Should auction listings and classifieds be searchable together?**
No. They have different price bases, different availability semantics — one you bid on, one you buy — and different data shapes. Merging them produces search results a user cannot act on. Keep them as separate surfaces and use the classifieds data to answer "what does this retail for" rather than to inflate an inventory count.
**Does the same car have the same value across Europe?**
No, and the variation is systematic rather than random — driven by local taxation, emissions regulation, fuel-type preference and fleet composition. A single European reference price is usually the wrong abstraction; compute per-market references where the sample supports it, and always include landed cost before treating a cross-border price difference as an opportunity.
---
# Vehicle images at scale: why hotlinking auction galleries fails
URL: https://thecarapi.com/blog/vehicle-image-cdn-api
Published: 2026-06-22 · Updated: 2026-08-07
Category: Data engineering
Images are the largest, most expensive and most fragile part of vehicle data — and the part teams discover late, usually in the form of a listings grid full of broken thumbnails.
A wholesale vehicle listing carries somewhere between twenty and sixty photographs. At a million live vehicles that is tens of millions of images — and unlike the specification fields, users actually look at these. A listing grid where a third of the thumbnails are broken reads as a broken product, regardless of how good the underlying data is.
The naive approach is to store the source image URL alongside the listing and let the browser fetch it. It works in development. Here is why it does not survive.
## Four reasons hotlinking fails
### 1. Source URLs expire
This is the fatal one. Auction platforms commonly stop serving media for lots that have closed — sometimes within days, sometimes after weeks, and rarely with any announcement. Live listings look fine. Your historical archive rots quietly from the oldest end, and by the time anyone notices, months of galleries are gone with no way to recover them.
### 2. Hotlink protection
Many sources check the `Referer` header or require a valid session cookie. The failure mode is genuinely nasty: images load for you (you visited the source recently), fail for your users, and behave differently across browsers depending on referrer policy. It presents as an intermittent bug and is frequently misdiagnosed for weeks.
### 3. File sizes built for a different use case
Source galleries are full-resolution JPEGs, commonly 2–6 MB each. Loading a twenty-four-card grid with one thumbnail each means fetching perhaps 60 MB to render a page that needs about 400 KB of imagery. On mobile that is not slow, it is unusable.
### 4. You have no control over availability
Your product's perceived performance becomes a function of seven third-party CDNs you have no relationship with, no SLA against, and no cache control over. One source having a slow morning becomes your incident.
> **The failure is silent and delayed** — Every one of these problems is invisible during development and for the first few weeks in production. They surface together, later, as "the site looks broken" — which is why image strategy belongs in the initial architecture rather than in a follow-up ticket.
## What an image vault has to do
Copying images is the easy part. These are the properties that determine whether the copy is actually worth its storage cost:
1. **Copy at ingest, not on demand.** Lazy copying means the first user to view an old lot triggers a fetch against a URL that may already be dead. Copy when the listing is first seen, while the source still serves it.
2. **Re-encode.** WebP at sensible quality typically cuts payload substantially against source JPEG with no visible difference in a listing grid.
3. **Serve multiple sizes.** A thumbnail grid and a full-screen gallery have completely different requirements, and serving one image for both wastes bandwidth in one direction or detail in the other.
4. **Stable URLs that outlive the lot.** The entire point. If the served URL breaks when the auction closes, you have built an expensive cache rather than an archive.
5. **Preserve ordering and role.** Which image is primary, which section of the vehicle each belongs to, exterior versus interior versus damage detail. Galleries presented in arbitrary order are noticeably worse to use.
6. **Record dimensions.** Without width and height in the payload, every image causes layout shift on load, which is both a user-experience problem and a Core Web Vitals penalty.
```bash
curl -s "https://api.thecarapi.com/api/auction-images/encar/38112900" \
-H "X-API-Key: $API_KEY"
```
_Galleries are addressed by the same `site/auction_id` pair as detail and price history, and return `served_url` alongside ordering, section and dimensions._
## Consuming galleries efficiently
Two patterns that account for most of the practical difference in page performance.
### Do not fetch galleries in search
Search results need one thumbnail per card. Full gallery payloads for twenty-four results is a large response containing data for images the user will almost certainly never open. Use the thumbnail on the search card and fetch the gallery only when a detail view opens.
```javascript
// Search card — thumbnail only, from the search response