classifieds

Classifieds feed

Retail classifieds aggregated from portals across Europe. Not auction inventory: no bidding, no auction end date, no detail payload and no gallery — a single remote thumbnail per listing. Classifieds are therefore never a valid site value on /api/search and never appear in /api/sites.

Ended and paid-placement ("promoted") rows are excluded from every response. Every multi-value filter is OR within the parameter and AND across parameters. A non-numeric value on a numeric parameter is a 400.

Selecting portals. The vocabulary is ~680 origin portals wide, which is why source_exclude exists — it is the only practical way to say "everything but". Unlike site on the auction side, an unrecognised portal is not an error: the vocabulary is scraped rather than fixed, so an unknown value simply matches nothing (or excludes nothing). A listing with no recorded portal survives an exclusion.

Reading total. The feed holds ~9.7M listings, so counting is bounded rather than exhaustive — see total_capped and total_unavailable. When you do not need a count, include_total=false is always the fastest option.

get/api/classifieds/listings

Request

  • Base URL: https://api.thecarapi.com
  • URL: https://api.thecarapi.com/api/classifieds/listings
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer
    • API key in query parameter api_key

Query parameters

countrystring
Example:de,at

Comma-separated country codes, case-insensitive.

brandstring
Example:BMW

Comma-separated brands, exact as published.

modelstring

Comma-separated models.

fuelstring
Example:diesel

Comma-separated normalized fuels.

gearboxstring
Example:automatic

Comma-separated normalized gearboxes.

sellerstring
Example:dealer

Comma-separated seller types.

sourcestring
Example:mobile.de

Comma-separated origin portals, case-insensitive.

source_excludestring
Example:mobile.de

Comma-separated origin portals to leave out, case-insensitive.

price_frominteger

Lower bound on the public EUR price.

price_tointeger

Upper bound on the public EUR price.

year_frominteger
Example:2018

Lower bound on registration year, inclusive.

year_tointeger
Example:2024

Upper bound on registration year, inclusive.

kilometers_frominteger

Lower bound on mileage in kilometres.

kilometers_tointeger

Upper bound on mileage in kilometres.

qstring

Substring match on title and description. Has no index behind it, so it is the filter most likely to set total_unavailable.

with_photoboolean

Only listings that carry a thumbnail.

sort'newest' | 'price_low' | 'price_high' | 'year_new' | 'year_old' | 'mileage_low'
include_totalboolean

false returns total: null and skips the count.

limitinteger

Page size. Capped at pagination.max_limit from GET /api/contract (100 by default); larger values are clamped down rather than rejected. Do not combine with page_size — that is a 400.

offsetinteger

0-based row offset. Do not combine with page — that is a 400. Bounded by pagination.max_offset (5000 by default) on archive, catalog, top-offers and classifieds; /api/search and /api/listVehicles have no offset cap.

pageinteger

1-based page number; maps to offset = (page - 1) * limit. Do not combine with offset.

page_sizeinteger

Alias for limit. Do not combine with limit.

Headers

If-None-Matchstring
Example:W/"6f1c0a9d8e"

Echo back the ETag from your last response for this URL. An unchanged page answers 304 Not Modified with no body. ETags are weak, so the tag stays valid whether or not the body came back compressed.

Response

Matching classifieds.

successboolean required
contract_versionstring

Matches info.version of this document.

request_idstring

Also returned as the X-Request-ID header.

server_timestring date-time

UTC ISO-8601 timestamp of the response.

data_updated_atstring date-time

Route-supplied data timestamp, falling back to server_time. Not a guaranteed source refresh time; inspect listing observation timestamps and live_price.fetched_at where available.

totalinteger nullable

null when totals are suppressed or could not be computed.

limitinteger
offsetinteger
pageinteger
page_sizeinteger
total_pagesinteger nullable

null when total is null.

max_pageinteger nullable

Deepest page reachable under the offset policy.

total_cappedboolean

true when counting stopped at 100,000. Read total as "100,000+" and page by offset rather than trusting total_pages. An unfiltered total is never capped — it is precomputed and exact.

total_unavailableboolean

true when total is null because the count did not finish in its budget. The listings themselves are complete and correct; the verdict is cached for five minutes.

Example response

{
  "success": true,
  "contract_version": "2026-09-03",
  "listings": [
    {
      "reference_id": "tp-91744022",
      "title": "BMW 320d Touring",
      "brand": "BMW",
      "model": "3 Series",
      "engine": "320d",
      "year": 2016,
      "price_eur": 12500.5,
      "mileage_km": 180000,
      "fuel_norm": "diesel",
      "gearbox_norm": "automatic",
      "colour": "black",
      "doors": "5",
      "country": "Germany",
      "country_code": "de",
      "region": "Bayern",
      "seller_type": "dealer",
      "source_site": "mobile.de",
      "photo_count": 12,
      "published": "2026-07-30"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.