Coches.net API & Scraper
The Coches.net API returns live used-car listings from Spain's largest car marketplace as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
`search` takes the same filters the site itself offers — free text, make id, model id, price range, model year, mileage, horsepower, province, fuel type, gearbox, private-vs-dealer and nearly-new (Km0) — and returns the source's own result total and page count alongside the rows, plus the live result count behind every make, fuel and province id so you can size a segment before paging it. Each row carries the car's id, canonical URL, title, make and model with their ids, year, mileage, the cash asking price and the separate financed price, the monthly instalment where the dealer publishes one, fuel, power, environmental label, province, city, region, warranty, whether the seller is a professional, and the photo list. `listing` resolves any row id into the full advert: the seller's own description, factory specifications (engine, body, consumption), the standard and optional equipment lists, financing terms, the site's own market-average price for that car, the VIN where a history report is published, and the dealer's name, address, phone, website, rating and stock page. `reference` returns all 166 manufacturers with their ids and 1 688 model ids, so names can be translated into the ids search takes. One ReefAPI key, one credit pool, the standard { ok, data, meta, error } envelope.
What the filters do, measured on 2026-10-06
Every filter below was checked twice in the same run: once against the unfiltered total (268 873 cars) and once against the rows it returned, so a filter that the site accepts and then ignores is not on this page. Both counts are printed because the second is the one that can disagree.
| Filter | Unfiltered -> filtered | Rows that obeyed it |
|---|---|---|
| make_id (BMW = 7) | 268 873 -> 21 429 | 35 of 35 |
| model_id (BMW Serie 1 = 539) | 268 873 -> 3 624 | 35 of 35 |
| price_min / price_max (5 000-10 000 EUR) | 268 873 -> 51 470 | 35 of 35 |
| year_min / year_max (2020-2024) | 268 873 -> 88 325 | 35 of 35 |
| km_max (50 000 km) | 268 873 -> 55 376 | 35 of 35 |
| fuel_type_id (1 = diesel) | 268 873 -> 122 084 | 35 of 35 |
| province_id (Madrid = 28) | 268 873 -> 53 961 | 35 of 35 |
| query (free text, "gti") | 268 873 -> 2 440 | text match, not row-checkable |
| seller_type = professional (BMW) | 21 429 -> 10 554 | 35 of 35 |
| seller_type = private (BMW) | 21 429 -> 10 879 | 35 of 35 |
| transmission = automatic (BMW) | 21 429 -> 14 078 | gearbox is not on a search row |
| condition = nearly_new (Km0 / demo) | 268 873 -> 3 082 | 35 of 35 |
Body type is NOT offered as a search filter, on purpose. The source accepts it and the total moves, but the rows disagree with their own body-type field: 35 of 35 obeyed it for one id, 31 of 35 for another and only 13 of 35 for a third. Every row carries `body_type_id`, so filter on it yourself. Model NAMES are not a filter either - the source accepts a model name and returns the unfiltered make, so only `model_id` is accepted and `reference` gives you the ids.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/coches/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"make_id": 7,
"province_id": 28,
"year_min": 2020,
"km_max": 40000,
"limit": 10
}
}{
"ok": true,
"meta": {
"api": "coches",
"endpoint": "search",
"mode": "live",
"latency_ms": 3421.1,
"record_count": 10,
"bytes": 1574642,
"cache_hit": false,
"stop_reason": "limit_reached",
"charged_credits": 1,
"version": "1.0.0",
"request_id": "b6836dd084e34e40",
"queue_ms": 23,
"fetched_at": "2026-10-06T14:47:19.750Z"
},
"data": {
"page": 1,
"requested_page": 1,
"page_clamped": false,
"count": 10,
"window_size": 35,
"source_total": 546,
"source_total_pages": 19,
"has_more": true,
"source_filters_applied": {
"make_id": 7,
"model_id": null,
"price": {
"from": null,
"to": null
},
"year": {
"from": 2020,
"to": null
},
"kms": {
"from": null,
"to": 40000
},
"fuel_type_ids": [],
"body_type_ids": [],
"province_ids": [
28
],
"query": null,
"seller_type_id": 0,
"transmission_type_id": 0,
"sort_by": "relevance",
"sort_order": "DESC",
"page": 1
},
"requested_query_string": "MakeIds=7&MinYear=2020&MaxKms=40000&arrProvince=28",
"facet_counts": {
"makeId": {
"1": 50,
"3": 15,
"4": 393,
"6": 6,
"7": 546,
"8": 2,
"9": 6,
"11": 403,
"14": 172,
"15": 334,
"18": 394,
"19": 4,
"20": 9,
"21": 151,
"22": 480,
"23": 15,
"24": 141,
"25": 88,
"26": 17,
"27": 206,
"28": 851,
"29": 258,
"30": 72,
"31": 238,
"32": 293,
"33": 591,
"34": 182,
"35": 390,
"36": 3,
"39": 466,
"40": 186,
"41": 20,
"42": 16,
"43": 12,
"44": 36,
"46": 440,
"47": 475,
"48": 285,
"69": 43,
"146": 28,
"147": 6,
"149": 2,
"163": 1,
"173": 16,
"210": 130,
"222": 99,
"243": 17,
"1011": 153,
"1327": 4,
"1328": 1,
"1330": 3,
"1347": 1,
"1351": 3,
"1352": 57,
"1354": 23,
"1358": 70,
"1372": 1,
"1377": 14,
"1384": 17,
"1400": 280,
"1401": 6,
"1402": 17,
"1403": 1,
"1404": 69,
"1409": 2,
"1410": 13,
"1411": 19,
"1418": 1,
"1420": 53,
"1421": 15,
"1422": 2,
"1427": 9,
"1431": 5,
"1432": 16,
"1433": 3,
"1434": 43,
"1435": 8,
"1437": 11,
"1438": 6,
"1439": 1,
"1440": 2,
"1441": 1,
"1444": 21,
"1445": 2,
"1446": 4
},
"model": {
"70": 83,
"71": 25,
"177": 2,
"178": 5,
"291": 5,
"438": 14,
"515": 59,
"539": 86,
"880": 9,
"944": 71,
"1056": 2,
"1084": 41,
"1085": 1,
"1092": 57,
"1119": 3,
"1158": 10,
"1241": 38,
"1259": 8,
"1361": 3,
"1374": 3,
"1422": 3,
"1444": 6,
"1445": 7,
"1498": 3,
"1515": 2
},
"fuelTypeIds": {
"1": 74,
"2": 137,
"3": 22,
"4": 218,
"5": 93
},
"bodyTypeIds": {
"1": 189,
"2": 45,
"3": 19,
"4": 56,
"5": 10,
"6": 220
},
"provinceIds": {
"0": 1,
"1": 1,
"2": 21,
"3": 98,
"4": 62,
"6": 42,
"7": 18,
"8": 216,
"9": 5,
"10": 34,
"11": 29,
"12": 29,
"13": 22,
"14": 14,
"15": 36,
"16": 5,
"17": 20,
"18": 66,
"19": 2,
"20": 5,
"21": 6,
"22": 1,
"23": 40,
"24": 8,
"25": 15,
"26": 4,
"27": 14,
"28": 546,
"29": 223,
"30": 71,
"31": 11,
"32": 9,
"33": 22,
"34": 1,
"35": 112,
"36": 29,
"37": 9,
"38": 99,
"39": 4,
"40": 22,
"41": 109,
"42": 1,
"43": 40,
"44": 1,
"45": 81,
"46": 138,
"47": 28,
"48": 28,
"49": 18,
"50": 22
},
"luggageCapacity": {
"1": 1,
"2": 146,
"3": 391
}
},
"results": [
{
"listing_id": "71491333",
"url": "https://www.coches.net/bmw-serie-3-m340i-xdrive-auto-touring-5p-electrico-hibrido-2025-en-madrid-71491333-covo.aspx",
"title": "BMW Serie 3 M340i xDrive Auto. Touring",
"make": "BMW",
"make_id": 7,
"model": "Serie 3",
"model_id": 70,
"year": 2025,
"mileage_km": 9849,
"price_eur": 63490,
"financed_price_eur": null,
"price_basis": "cash_asking",
"currency": "EUR",
"includes_taxes": true,
"offer_type": "Ocasión",
"offer_type_id": 0,
"is_nearly_new": false,
"monthly_instalment_eur": null,
"fuel": "Híbrido",
"fuel_type_id": 4,
"body_type_id": 4,
"power_hp": 374,
"environmental_label": null,
"province": "Madrid",
"province_id": 28,
"city": "Villanueva del Pardillo",
"region": "Madrid",
"seller_is_professional": false,
"seller_name": null,
"seller_phone": "604983867",
"has_warranty": false,
"warranty_months": null,
"is_certified": false,
"is_promoted": true,
"published_at": "2026-10-06T09:39:48Z",
"created_at": "2026-09-11T10:35:54Z",
"image_count": 33,
"images": [
"https://a.ccdn.es/cnet/2026/09/11/71491333/2129677682_g.jpg",
"https://a.ccdn.es/cnet/2026/09/11/71491333/2129677746_g.jpg",
"https://a.ccdn.es/cnet/2026/09/11/71491333/2129678088_g.jpg"
]
},
{
"listing_id": "71490148",
"url": "https://www.coches.net/bmw-x1-m35i-xdrive-5p-gasolina-2025-en-madrid-71490148-covo.aspx",
"title": "BMW X1 M35i xDrive",
"make": "BMW",
"make_id": 7,
"model": "X1",
"model_id": 944,
"year": 2025,
"mileage_km": 38500,
"price_eur": 55900,
"financed_price_eur": 55900,
"price_basis": "cash_asking",
"currency": "EUR",
"includes_taxes": true,
"offer_type": "Ocasión",
"offer_type_id": 0,
"is_nearly_new": false,
"monthly_instalment_eur": 689.7528336034648,
"fuel": "Gasolina",
"fuel_type_id": 2,
"body_type_id": 6,
"power_hp": 300,
"environmental_label": "C",
"province": "Madrid",
"province_id": 28,
"city": "Pinto",
"region": "Madrid",
"seller_is_professional": true,
"seller_name": "AUTO GALLERY PREMIUM SL",
"seller_phone": "647697371",
"has_warranty": true,
"warranty_months": 24,
"is_certified": false,
"is_promoted": true,
"published_at": "2026-09-11T07:50:01Z",
"created_at": "2026-09-11T07:50:01Z",
"image_count": 34,
"images": [
"https://a.ccdn.es/cnet/vehicles/20763926/3549bb51-2b2e-4380-8a04-6fc7ee1e5d08.jpg",
"https://a.ccdn.es/cnet/vehicles/20763926/a1fbcdb6-c9a4-4c1a-8b49-19d28e8fd88a.jpg",
"https://a.ccdn.es/cnet/vehicles/20763926/77946e95-1183-4d01-a2cb-8d539d173618.jpg"
]
},
{
"listing_id": "71023992",
"url": "https://www.coches.net/bmw-serie-3-330e-xdrive-touring-5p-electrico-hibrido-2025-en-toledo-71023992-covo.aspx",
"title": "BMW Serie 3 330e xDrive Touring",
"make": "BMW",
"make_id": 7,
"model": "Serie 3",
"model_id": 70,
"year": 2025,
"mileage_km": 16846,
"price_eur": 47900,
"financed_price_eur": 43900,
"price_basis": "cash_asking",
"currency": "EUR",
"includes_taxes": true,
"offer_type": "Ocasión",
"offer_type_id": 0,
"is_nearly_new": false,
"monthly_instalment_eur": 559.06,
"fuel": "Híbrido enchufable",
"fuel_type_id": 5,
"body_type_id": 4,
"power_hp": 292,
"environmental_label": "0",
"province": "Toledo",
"province_id": 45,
"city": "Olías del Rey",
"region": "Castilla-La Mancha",
"seller_is_professional": true,
"seller_name": "BMW Alonso Pineda, S.L.",
"seller_phone": "925814998",
"has_warranty": true,
"warranty_months": 24,
"is_certified": false,
"is_promoted": true,
"published_at": "2026-07-08T16:58:31Z",
"created_at": "2026-07-08T16:58:31Z",
"image_count": 46,
"images": [
"https://a.ccdn.es/cnet/vehicles/20374086/6f937037-9e82-45c1-949a-03932b778690.jpg",
"https://a.ccdn.es/cnet/vehicles/20374086/b14137f8-2bab-43ab-b4c3-6263c80740fa.jpg",
"https://a.ccdn.es/cnet/vehicles/20374086/f9d7c77d-dd7c-43c5-b705-0858de6d2371.jpg"
]
}
]
}
}What the Coches.net API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | 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). | Price-intelligence teams call search to search Spain's largest used-car marketplace with the site's own filters. | query, make_id, model_id, price_min, price_max, ... |
| listing | 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. | Classifieds aggregators call listing to get full detail for one car. | listing_id |
| reference | 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. | Resale and arbitrage tools call reference to get the filter vocabulary, read live from the source. | none |
Call search from your stack
curl -X POST https://api.reefapi.com/coches/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"make_id":7,"province_id":28,"year_min":2020,"km_max":40000,"limit":10}'import requests
r = requests.post(
"https://api.reefapi.com/coches/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"make_id": 7,
"province_id": 28,
"year_min": 2020,
"km_max": 40000,
"limit": 10
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/coches/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"make_id": 7,
"province_id": 28,
"year_min": 2020,
"km_max": 40000,
"limit": 10
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.coches.search with {"make_id":7,"province_id":28,"year_min":2020,"km_max":40000,"limit":10}.Who uses this API and why
- Price-intelligence teams track Spanish used-car prices by make, model, year and mileage band, using the source's own result totals to size each segment.
- Dealer and lead-gen tools pull a province's live inventory with the dealer's name, address, phone and rating attached to every car.
- Residual-value and insurance models compare a car's asking price against the market average the source publishes for that exact car.
- Vehicle-history and VIN services resolve listing ids into VINs where the source publishes a history report, together with the factory specification set.
- Marketplace aggregators mirror Spanish supply by paging a filtered search and reading the source's own page count instead of guessing when to stop.
Questions developers ask before integrating
Does search cover the whole Coches.net catalogue or just one brand?
The whole catalogue. An unfiltered call read 268 873 live cars on 2026-10-06 and every filter is optional, so you can browse the lot or narrow to a single model in one province. The source's own total and page count come back on every response, so you always know how much is behind the query you sent.
What is the difference between price_eur and financed_price_eur?
price_eur is the cash asking price - the number the advert prints as the price to pay. financed_price_eur is the lower price the dealer offers if you take their finance, and monthly_instalment_eur is the instalment behind it. They are separate fields on purpose: on 127 of 200 sampled rows a financed price existed and it was usually lower, so collapsing them into one price would quietly understate the market. On the detail endpoint the cash price is also checked against the source's own financing block and the result is published as price_witness_agrees - it agreed on 6 of 6 cars checked.
Do I get the VIN?
Where Coches.net publishes a vehicle-history report for that car, yes - the 17-character VIN comes back in the vin field. It is not published for every advert: 2 of 6 cars sampled across six different segments had one. When it is absent the field is null, never guessed.
Are dealer details included, and private sellers too?
Yes. listing returns the seller block as the site publishes it: for a dealer that is the trading name, street address, city, province, postal code, coordinates, phone, website, star rating, review count and the link to their stock page. For a private advert it is the display name the seller chose and their phone. Both kinds are in the catalogue - of 21 429 BMWs, 10 554 were professional and 10 875 private.
How do I find the make and model ids?
Call reference once. It returns all 166 manufacturers with their ids and 1 688 model ids under them, plus the province index and the live result count behind each make, fuel and province id. Those ids are what search takes; the names are not accepted because the source ignores a model name and silently returns the unfiltered make.
How far can I page, and how do I know when to stop?
The response carries source_total_pages from the site itself and has_more derived from it - use those. Do not loop until the rows run out: past the last page the source still answers 200 with a full window of rows, so a naive loop never terminates. When you ask beyond the end, page_clamped comes back true. A measured example: BMW had 715 pages, page 2 returned 34 rows and page 4 000 returned 34 different rows with page_clamped set.
How many cars come back per page?
The source window is variable - 30 to 35 rows were measured on the same filters at different times, so the page size is not fixed and is not promised. limit caps what you receive from that window (1-35, default 20) and window_size tells you how many the source actually published.
What does an empty result look like?
An honest zero. A deliberately impossible filter (BMWs between 9.99 and 10 million euro) returned ok with source_total 0 and no rows. A total above zero is never returned with an empty row list - that combination is treated as a source change and reported as an error instead of a silent empty success. A listing that has been taken down returns NOT_FOUND, because the source redirects it back to the search page.
Which fields can be empty?
Counted over 200 rows across eight different segments: listing_id, url, title, make, model, year, mileage_km, price_eur, fuel, province, region, warranty flags and the offer type were 200 of 200. financed_price_eur 127 of 200, monthly_instalment_eur 88 of 200, environmental_label 137 of 200, warranty_months 141 of 200, seller name 146 of 200, seller phone 183 of 200, city 180 of 200, power_hp 181 of 200, images 199 of 200. Anything the source does not publish comes back null rather than copied from somewhere else.
What is the Coches.net API?
Coches.net API is a ReefAPI endpoint group for spain's biggest used-car marketplace: filtered search, full car detail, vin and dealer. It returns live JSON through POST requests under /coches/v1.
Is the Coches.net API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Coches.net calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Coches.net login or account?
No login to Coches.net is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Coches.net data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Coches.net API use?
Coches.net actions currently cost 2-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.