# Coches.net — Spain used-car marketplace

> Search Spain's largest used-car marketplace with the site's own filters: free text, make, model, price, year, mileage, power, province, fuel, body type, transmission and seller type, with sorting and paging. Every filter below was measured to change the result total AND to hold on every returned row; filters the source accepts but ignores are deliberately not exposed. Call with no filters to browse the whole live catalogue (268k+ cars on 2026-10-06).
> ReefAPI engine `coches` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/coches/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/coches/v1/search — 3 credits
Search Spain's largest used-car marketplace with the site's own filters: free text, make, model, price, year, mileage, power, province, fuel, body type, transmission and seller type, with sorting and paging. Every filter below was measured to change the result total AND to hold on every returned row; filters the source accepts but ignores are deliberately not exposed. Call with no filters to browse the whole live catalogue (268k+ cars on 2026-10-06).

**Parameters:**
- `query` (string, optional) — Free-text search over the listing text, e.g. 'gti', 'xdrive', '4x4'. Measured: 268 790 unfiltered -> 2 440 for 'gti'.
- `make_id` (integer, optional) — Manufacturer id as published by the site (BMW = 7, AUDI = 4, VOLKSWAGEN = 47). The full list of 166 makes with ids comes from the `reference` action.
- `model_id` (integer, optional) — Model id within the make, from the `reference` action (BMW Serie 1 = 539). Model NAMES are not a filter on this source: passing a name is ignored upstream, so only the id is accepted.
- `price_min` (integer, optional) — Minimum cash asking price in EUR.
- `price_max` (integer, optional) — Maximum cash asking price in EUR.
- `year_min` (integer, optional) — Earliest model year.
- `year_max` (integer, optional) — Latest model year.
- `km_min` (integer, optional) — Minimum odometer reading in kilometres.
- `km_max` (integer, optional) — Maximum odometer reading in kilometres.
- `hp_min` (integer, optional) — Minimum engine power in metric horsepower (CV).
- `hp_max` (integer, optional) — Maximum engine power in metric horsepower (CV).
- `province_id` (integer, optional) — Spanish province id as the source numbers them (Madrid = 28, Barcelona = 8, Sevilla = 41, Valencia = 46). Live ids and their result counts are in `reference.facet_counts.provinceIds`.
- `fuel_type_id` (integer, optional) — Fuel type id as the source numbers them (1 = diesel, 2 = petrol, 4 = hybrid/electric). Live ids with counts are in `reference.facet_counts.fuelTypeIds`; every returned row carries both `fuel_type_id` and the printed `fuel` label, and all 35 rows matched on 2026-10-06.
- `transmission` (enum, optional) — Gearbox. Measured on BMW: 21 412 unfiltered -> 14 062 automatic. [one of: automatic, manual]
- `seller_type` (enum, optional) — Who is selling. Measured on BMW: 10 539 professional + 10 875 private = 21 414 of a 21 412 total, and every returned row's `seller_is_professional` matched. [one of: professional, private]
- `condition` (enum, optional, default "any") — Vehicle condition. Measured: no filter returns 268 779 cars (used and nearly-new together); `nearly_new` returns 3 082, and every row came back Km0 or dealer demo. Each row also carries `offer_type` and `is_nearly_new` so you can tell them apart yourself. [one of: any, nearly_new]
- `sort` (enum, optional, default "relevance") — Sort field. `relevance` is the site's own default ordering and promoted cars can appear in it. [one of: relevance, price, km, year, hp, title]
- `order` (enum, optional, default "desc") — Sort direction. Ignored when `sort` is `relevance`. [one of: asc, desc]
- `page` (integer, optional, default 1) — 1-based page. The source publishes `source_total_pages`; a page beyond it still answers, so `page_clamped` is returned to say when you asked past the end.
- `limit` (integer, optional, default 20) — Rows returned from this page. The source window measured 30-35 rows per page and is variable, so a limit above the window returns the whole window.

**Returns:** results[] with listing_id, url, title, make, make_id, model, model_id, year, mileage_km, price_eur, financed_price_eur, monthly_instalment_eur, currency, includes_taxes, offer_type, offer_type_id, is_nearly_new, fuel, fuel_type_id, body_type_id, power_hp, environmental_label, province, province_id, city, region, seller_is_professional, seller_name, seller_phone, has_warranty, warranty_months, is_certified, is_promoted, published_at, created_at, images[] and image_count; plus source_total, source_total_pages, has_more, page_clamped, window_size, source_filters_applied (the filters the source says it applied) and facet_counts (live result counts per make/fuel/body/province id).

**Example request body:**
```json
{
  "make_id": 7,
  "province_id": 28,
  "year_min": 2020,
  "km_max": 40000,
  "limit": 10
}
```

### POST https://api.reefapi.com/coches/v1/listing — 3 credits
Full detail for one car: everything the search row has plus the seller's full advert text, the VIN where the source publishes a history report, factory specifications (engine, body, consumption), the standard/optional equipment lists, financing terms, the site's own market-average price, and the dealer's name, address, phone, website, rating and stock page. A listing that no longer exists returns NOT_FOUND rather than an empty success.

**Parameters:**
- `listing_id` (string, required) — The numeric id returned by `search` (e.g. 71378787). The full listing URL, or its path, is accepted too — the numeric id resolves used, Km0 and dealer-demo cars alike, so you never have to keep the slug.

**Returns:** One object: every search field plus description, version, version_id, vin, colour, transmission, traction, warranty_text, has_official_warranty, price_drop_eur, market_average_price_eur, price_rank_indicator, cash_price_second_witness_eur, price_witness_agrees, financing{}, specifications{body,engine,consumption}, equipment[], views, favourites, vehicle_history_report_url and seller{id,name,is_professional,phone,website, stock_url,address,city,province,postal_code,coordinates,rating_average, rating_count,plan}.

**Example request body:**
```json
{
  "listing_id": "71378787"
}
```

### POST https://api.reefapi.com/coches/v1/reference — 2 credits
The filter vocabulary, read live from the source: all 166 manufacturers with their ids and every model id under them (1 700+ models), the province index, and the live result count behind each make / fuel / body-type / province id. Call this once to translate names into the ids `search` takes.

**Parameters:** none

**Returns:** makes[]{make_id, make, model_count, models[]{model_id, model}}, make_count, model_count, provinces[]{province, slug, url}, facet_counts{makeId, fuelTypeIds, bodyTypeIds, provinceIds, luggageCapacity}.

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=coches
- Human docs page: https://reefapi.com/docs/coches
- Overview page: https://reefapi.com/coches-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt