Cars.co.za API & Scraper
The Cars.co.za API turns cars.co.za, South Africa's largest car marketplace, into clean JSON in six actions.
🤖 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 covers the whole live catalogue — 76,076 listings on 2026-10-01, of which 65,553 used and 10,523 new — and narrows it by free-text keyword, make, model, variant, new or used, dealer or private seller, price band in rand, odometer band, model-year band, monthly instalment band, engine-capacity band, body type, province, town, transmission, fuel, colour, seat count, two or four wheel drive, passenger or commercial, induction type, the deal badge Cars.co.za itself puts on the car, the selling dealership's minimum rating, and whether to include motorcycles. Every row carries the listing id and canonical URL, the title, make, model and variant, the model year, the asking price in rand, the pre-cut price where the price has dropped, the monthly instalment Cars.co.za estimates on its own published rate card, the odometer both as a number and as the source printed it, the full spec summary, the deal badges, the dealer's own description, the feature list, every photo URL, the province and town, and a seller block with the dealership's name, suburb, province, coordinates, star rating and rating count — or, for the 211 private listings, the seller block the source publishes for an individual. detail adds Cars.co.za's complete manufacturer spec table grouped as the site groups it, the site's own highlight verdicts with their numbers, the date the car was listed, the dealership's own stock reference and the sold flag. dealers is the whole dealer directory, 1,710 active dealerships with street address, suburb, province, coordinates, dealer group, rating, how many cars they list, their three most-listed makes and their published phone number. dealer returns one dealership plus the Google reviews Cars.co.za publishes for it. dealer_stock returns every car one dealership currently lists. filters returns the live filter vocabulary with the number of listings behind every value, including the whole make to model to variant tree across 100 makes, so you can size a query before you run it and never have to guess a spelling. No Cars.co.za account, one ReefAPI key and the standard { ok, data, meta, error } envelope.
The money fields, and why there is no field called price
A Cars.co.za row carries up to three different money figures and they do not mean the same thing, so this API never blends them and never ships a bare price key. Fill rates below are over 120 distinct live listings sampled round-robin across nine surfaces: used cars, new cars, dealer stock, private sellers, double-cab bakkies, buses, panel vans, electric cars and motorcycles.
| Field | What it is | How often it was filled |
|---|---|---|
| price_zar | The asking price today, in South African rand. Verified against the money strings the listing page itself prints on 8 listings: 8 matched, 0 mismatched. A zero is returned as null, never as a price. | 120 of 120 |
| previous_price_zar | The price before Cars.co.za cut it, on listings carrying the price-drop badge. Returned separately and never used as the price. | 7 of 120 |
| monthly_instalment_zar | Not a price: the monthly finance instalment Cars.co.za estimates on the rate card its own pages publish — 12.75 % a year, 72 months, 10 % deposit. Private listings never carry one. | 85 of 120 |
| mileage_km | The odometer reading as a number, parsed from the string the source prints. Agreed with that string on 113 of 113 rows that had one. | 113 of 120 |
| mileage_text | The odometer exactly as Cars.co.za printed it, e.g. "72 000 Km". Kept because a brand-new car is printed as "-1 Km", which is returned as a null mileage_km rather than as minus one kilometre. | 120 of 120 |
| deal_tags | Cars.co.za's own badges on the listing: great deal, good deal and fair deal are its price verdict against its own guide price; price drop means the advertised price was cut; also fast seller, performance, luxury and classic. | 62 of 120 |
Every figure above is the source's own. The instalment is the one number on the page that Cars.co.za computes rather than reports, which is why it is named for what it is and kept out of the price fields. 0 of the 120 rows published a price of zero, because a zero is nulled on the way out.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/cars-co-za/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"max_results": 20
}
}{
"ok": true,
"meta": {
"api": "cars-co-za",
"endpoint": "search",
"mode": "live",
"latency_ms": 1666.2,
"record_count": 20,
"bytes": 71791,
"cache_hit": false,
"stop_reason": "limit_reached",
"upstream_requests": 1,
"charged_credits": 1,
"version": "1.0.0",
"request_id": "806d70e067a5469d",
"queue_ms": 1.4
},
"data": {
"results": [
{
"listing_id": "11264550",
"url": "https://www.cars.co.za/for-sale/used/2020-Hyundai-Kona-1.0-TGDI-Executive-Western-Cape-Cape-Town/11264550/",
"title": "2020 Hyundai Kona 1.0 TGDI Executive",
"make": "Hyundai",
"model": "Kona",
"variant": "1.0 TGDI Executive",
"variant_short": "1.0 TGDI",
"year": 2020,
"condition": "Used",
"price_zar": 229900,
"previous_price_zar": null,
"monthly_instalment_zar": 4126,
"currency": "ZAR",
"mileage_km": 75000,
"mileage_text": "75 000 Km",
"body_type": "SUV",
"transmission": "Manual",
"fuel_type": "Petrol",
"engine_litres": 1,
"engine_type": "Turbocharged",
"drivetrain": "4X2",
"seats": "5",
"colour": "Silver",
"vehicle_kind": "passenger",
"condition_grade": "Excellent",
"deal_tags": [],
"description": "- Nationwide Delivery \n- Trade Ins Welcome\nContact Jetour Tygervalley today to arrange a viewing or book your test drive. Don’t miss this opportunity to own this 2020 Hyundai Kona Executive Manual — a stylish and versatile compact SUV offering a refined driving experience, comfortable interior, impressive practicality, and excellent everyday value. The Kona is an ideal choice for both everyday commuting and weekend adventures.\nTrust in Hatfield Motor Group for a seamless car buying experience.",
"features": [
"ABS",
"Full service record",
"Electric Windows"
],
"images": [
"https://img-ik.cars.co.za/ik-seo/carsimages/11264550/2020-Hyundai-Kona-10-TGDI-Executive.jpg?v=3951313901",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264550_2/2020-Hyundai-Kona-10-TGDI-Executive.jpg?v=3951313901",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264550_3/2020-Hyundai-Kona-10-TGDI-Executive.jpg?v=3951313901"
],
"image_count": 22,
"province": "Western Cape",
"city": "Cape Town",
"seller": {
"kind": "dealer",
"name": "Jetour Tygervalley",
"dealer_id": "7827",
"locality": "Cape Town",
"province": "Western Cape",
"latitude": -33.8437432,
"longitude": 18.6772617,
"rating": 4.6,
"rating_count": 64,
"is_featured": null,
"nada_member": true,
"phone": null,
"whatsapp": null
},
"listing_code": "pp6eppukqZg=",
"is_sold": null,
"listed_at": null,
"dealer_reference": null
},
{
"listing_id": "11264549",
"url": "https://www.cars.co.za/for-sale/used/2026-Volkswagen-Polo-1.0-TSI-Western-Cape-Cape-Town/11264549/",
"title": "2026 Volkswagen Polo 1.0 TSI",
"make": "Volkswagen",
"model": "Polo",
"variant": "1.0 TSI",
"variant_short": "1.0 TSI",
"year": 2026,
"condition": "Used",
"price_zar": 309900,
"previous_price_zar": null,
"monthly_instalment_zar": 5562,
"currency": "ZAR",
"mileage_km": 12000,
"mileage_text": "12 000 Km",
"body_type": "Hatchback",
"transmission": "Manual",
"fuel_type": "Petrol",
"engine_litres": 1,
"engine_type": "Turbocharged",
"drivetrain": "4X2",
"seats": "5",
"colour": "Smoky Grey",
"vehicle_kind": "passenger",
"condition_grade": "Excellent",
"deal_tags": [],
"description": "- Balance of 3 Year / 120 000km Warranty\n- Balance of 3 Year / 45 000km Service Plan\n- Nationwide Delivery \n- Trade Ins Welcome\nContact Jetour Tygervalley today to arrange a viewing or book your test drive. Don’t miss this opportunity to own this 2026 Volkswagen Polo TSI — a stylish and well-equipped hatchback offering a refined driving experience, modern technology, impressive practicality, and excellent everyday value.\nTrust in Hatfield Motor Group for a seamless car buying experience.",
"features": [
"ABS",
"Full service record",
"Electric Windows"
],
"images": [
"https://img-ik.cars.co.za/ik-seo/carsimages/11264549/2026-Volkswagen-Polo-10-TSI.jpg?v=2625860475",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264549_2/2026-Volkswagen-Polo-10-TSI.jpg?v=2625860475",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264549_3/2026-Volkswagen-Polo-10-TSI.jpg?v=2625860475"
],
"image_count": 21,
"province": "Western Cape",
"city": "Cape Town",
"seller": {
"kind": "dealer",
"name": "Jetour Tygervalley",
"dealer_id": "7827",
"locality": "Cape Town",
"province": "Western Cape",
"latitude": -33.8437432,
"longitude": 18.6772617,
"rating": 4.6,
"rating_count": 64,
"is_featured": null,
"nada_member": true,
"phone": null,
"whatsapp": null
},
"listing_code": "qpyZpaCpqpo=",
"is_sold": null,
"listed_at": null,
"dealer_reference": null
},
{
"listing_id": "11264548",
"url": "https://www.cars.co.za/for-sale/used/2026-Ford-Ranger-2.2-TDCi-XL-Double-Cab-Limpopo-Bela-Bela/11264548/",
"title": "2026 Ford Ranger 2.2 TDCi XL Double-Cab",
"make": "Ford",
"model": "Ranger",
"variant": "2.2 TDCi XL Double-Cab",
"variant_short": "XL",
"year": 2026,
"condition": "Used",
"price_zar": 224900,
"previous_price_zar": null,
"monthly_instalment_zar": 4037,
"currency": "ZAR",
"mileage_km": 207000,
"mileage_text": "207 000 Km",
"body_type": "Double Cab Bakkie",
"transmission": "Manual",
"fuel_type": "Diesel",
"engine_litres": 2.2,
"engine_type": "Turbocharged",
"drivetrain": "4X2",
"seats": "5",
"colour": "White",
"vehicle_kind": "ab",
"condition_grade": "Excellent",
"deal_tags": [],
"description": "Discover the capable Ford Ranger 2.2 TDCi XL Double-Cab, a robust and reliable pick-up finished in sleek white. This excellent condition vehicle is packed with features to keep you comfortable and confident on the road. Enjoy modern tech such as Apple CarPlay and Android Auto, alongside air conditioning and climate control for a perfect cabin environment. The Ranger’s full service record ensures peace of mind, complemented by safety features like airbags, ABS, and ISOFIX. Parking becomes a breeze with the rear-view camera and park distance control, while cruise control adds to your driving com",
"features": [
"ABS",
"Full service record",
"Electric Windows"
],
"images": [
"https://img-ik.cars.co.za/ik-seo/carsimages/11264548/2026-Ford-Ranger-22-TDCi-XL-Double-Cab.jpg?v=4232379038",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264548_2/2026-Ford-Ranger-22-TDCi-XL-Double-Cab.jpg?v=4232379038",
"https://img-ik.cars.co.za/ik-seo/carsimages/11264548_3/2026-Ford-Ranger-22-TDCi-XL-Double-Cab.jpg?v=4232379038"
],
"image_count": 19,
"province": "Limpopo",
"city": "Bela-Bela",
"seller": {
"kind": "dealer",
"name": "Haval Bela Bela",
"dealer_id": "7043",
"locality": "Bela-Bela",
"province": "Limpopo",
"latitude": -24.8875928,
"longitude": 28.2949615,
"rating": 4.9,
"rating_count": 71,
"is_featured": null,
"nada_member": false,
"phone": null,
"whatsapp": null
},
"listing_code": "ppqZppuprJ8=",
"is_sold": null,
"listed_at": null,
"dealer_reference": "2017 Ford Ranger 2.2TDCi MT (7265)"
}
],
"total_available": 76078,
"returned": 20,
"offset": 0,
"page_ceiling": 120,
"sort": "relevance"
}
}What the Cars.co.za API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Cars.co.za's live South African stock — 76,076 listings on 2026-10-01, of which 65,553 used and 10,523 new, from 1,710 dealerships plus 211 private sellers. Every row carries the listing id, the canonical URL, the asking price in rand, the odometer, the full spec summary, the deal badge Cars.co.za itself puts on the car, all photo URLs, and the seller block (dealership name, suburb, province, coordinates and rating). 🔴 Measured: search rows carry NO phone number — 0 of 120 — because the source only publishes the dealership's tracking number on `detail` and `dealers` (99 of 100 dealerships there have one). `total_available` is the source's own count for your exact query, so you can see what each filter did. 🔴 One call returns at most 120 rows (measured ceiling) — use `offset` to page, which was measured working to the end of the catalogue, with no overlap between pages. All filters are optional; an unmatched filter returns `ok:true` with 0 results and a warning, never an error. | Price-intelligence teams call search to search Cars.co.za's live South African stock. | query, make, model, variant, condition, ... |
| detail | One listing in full, from the source's own listing endpoint: everything a `search` row carries plus the complete manufacturer spec table grouped as Cars.co.za groups it (summary, engine, performance, dimensions, …), the site's own `highlights` verdicts with their numbers, the date the car was listed, the dealership's own stock reference, and the sold flag. Measured on a dealer car, a private-seller car and a motorcycle: all three answer, and motorcycles come back with an empty spec table because the source publishes none for them. A dead id returns NOT_FOUND. | Classifieds aggregators call detail to get one listing in full, from the source's own listing endpoint. | listing_id |
| dealers | The Cars.co.za dealer directory — 1,710 active dealerships on 2026-10-01 — with street address, suburb, province, coordinates, dealer group, rating and rating count, how many cars they currently list, their three most-listed makes, their Cars.co.za profile URL and their published phone number. Filters measured in the same run: `query`/`name` → 32 for BMW, `province` → 858 in Gauteng, `city` → 53 in Sandton, `featured_only` → 198. 🔴 Four parameters the source accepts and then ignores (`popular_makes`, `top_make`, a province under the vehicle spelling, and a rating range) are deliberately NOT exposed. | Resale and arbitrage tools call dealers to get the Cars.co.za dealer directory. | query, province, city, featured_only, sort, ... |
| dealer | One dealership's profile, plus the Google reviews Cars.co.za publishes for it (reviewer name, star rating, relative date and the review text) when `include_reviews` is left on. A dealer id that does not exist returns NOT_FOUND rather than an empty success. | Lead-generation teams call dealer to get one dealership's profile, plus the Google reviews Cars.co.za publishes for it (reviewer name,…. | dealer_id, include_reviews |
| dealer_stock | Every vehicle one dealership currently lists, in the same row shape as `search`, dearest first by default. Take `dealer_id` from `dealers` or from `seller.dealer_id` on any search row. Measured: dealer 8365 → 10 cars, dealer 7914 → 17. | Price-intelligence teams call dealer_stock to get every vehicle one dealership currently lists, in the same row shape as `search`, dearest firs…. | dealer_id, sort, max_results, offset, bikes |
| filters | The live filter vocabulary straight from the source, with the number of listings behind every value — so you can size a query before you run it, and you never have to guess a spelling. `facet=make_model_variant` returns the whole tree (100 makes, every model, every variant, counts on all three levels, ~167 KB). `facet=price` / `mileage` / `year` / `monthly_price` return the source's own two-sided ladder (how many cars sit above each rung and below each rung). Any `search` filter can be narrowed by the same values. | Classifieds aggregators call filters to get the live filter vocabulary straight from the source, with the number of listings behind every…. | facet |
Call search from your stack
curl -X POST https://api.reefapi.com/cars-co-za/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"max_results":20}'import requests
r = requests.post(
"https://api.reefapi.com/cars-co-za/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"max_results": 20
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/cars-co-za/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"max_results": 20
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.cars-co-za.search with {"max_results":20}.Who uses this API and why
- South African used-car pricing and valuation: pull a make, model and variant with a model-year and odometer band and read the asking-price distribution, then narrow by province to see how the same car is priced in Gauteng against the Western Cape.
- Dealer intelligence: the full 1,710-dealership directory with coordinates, group, rating, rating count and live stock count, plus every car a named dealership is listing, so you can size a competitor's forecourt or map coverage by town.
- Market-share and mix tracking: the filters action returns a listing count on every make, model, variant, body type, fuel, province, colour and seat count, so a single cheap call gives the whole market mix — for example Toyota 11,519 listings against Volkswagen 9,494, or SUVs 33,823 against double-cab bakkies 9,071.
- Lead sourcing and classified aggregation: new-versus-used and dealer-versus-private are separate, measured filters, so you can pull only the 211 private listings or only the 75,865 dealer listings, with the canonical listing URL on every row.
- Electrification and import-brand research: fuel type is a measured filter with the source's own counts — 596 electric, 1,419 hybrid and 659 plug-in hybrid against 48,574 petrol — and the make facet shows how far the Chinese brands have come, with Chery at 2,096 listings and Haval at 1,932.
Questions developers ask before integrating
How many listings are there, and does the count come from you or from Cars.co.za?
From Cars.co.za. Every search returns total_available, which is the source's own count for your exact query. On 2026-10-01 the unfiltered figure was 76,076, the identical number cars.co.za printed on its own used-car page in the same minute, and it was still 76,076 when re-measured minutes later. Used and new split it exactly: 65,553 plus 10,523 is 76,076. Dealer and private split it exactly too: 75,865 plus 211.
How many rows can one call return?
Up to 120, and that is the source's ceiling rather than ours: asking for 200 or 500 still returns exactly 120. Below that you get exactly what you ask for — 20 gives 20, 50 gives 50, 100 gives 100. Use offset to page past it. Offset paging was measured working all the way to the end of the catalogue at offset 76,060, and past the end it returns zero rows with no error.
Do pages overlap when I page through results?
No. Four pages of 20 rows at offsets 0, 20, 40 and 60 under the same sort returned 80 rows and 80 distinct listing ids, in both measurement runs. This API also does not ask Cars.co.za to inject promoted listings into the page, which its own website does, so sponsored stock never arrives in your results unannounced.
Do the filters actually narrow the result, or are some of them decoration?
Every filter in this API was measured against the unfiltered total of 76,076 in the same run, and only the ones that moved it are exposed. Measured: keyword Hilux 2,642, make Toyota 11,519, Toyota Starlet 1,056, price 100,000 to 200,000 13,566, odometer under 50,000 40,453, years 2023 to 2026 43,911, body type SUV 33,823, province Gauteng 42,243, town Sandton 2,881, automatic 48,673, diesel 24,743, white 36,379, seven seats 7,152, four-wheel drive 16,921, commercial 16,886, turbocharged 46,242, the price-drop badge 4,845, dealerships rated four and up 57,941. Nine parameters that Cars.co.za accepts with a 200 and then ignores — including a roadworthy flag, a finance flag, a condition grade and a sold flag — were tested, found to return the full 76,076 unchanged, and left out, because a filter that does not bite is worse than no filter at all.
What happens if nothing matches my filters?
You get a successful response with an empty results array, the source's own total of 0, and a note in meta saying this is Cars.co.za's empty answer rather than a failure. An unmatchable make was tested for exactly this. The opposite case is also handled: if Cars.co.za reports listings and none can be read, you get an explicit schema error instead of a quiet empty success.
Is the seller included, and does it include a phone number?
The seller is on every row: 120 of 120 carried a seller name, kind and province, and 114 of 120 a dealer id you can pass to dealer and dealer_stock. Coordinates were on 118 of 120 and a star rating on 97 of 120. A phone number, however, is NOT on a search row — measured 0 of 120. Cars.co.za publishes the dealership's number on the dealer directory, where 99 of 100 dealerships had one, and on the single-listing detail record. Private listings are published as the source publishes them, as Private Seller with a suburb and province and no contact route.
Why is the odometer empty on some new cars?
Because a brand-new car has no reading and Cars.co.za prints minus one kilometre for it. That is returned as a null odometer with the source's own string kept beside it, rather than as a mileage of minus one. On the new-car surface this is half the rows — 10 of 20 — and on the used surface it was 20 of 20 filled. Cars.co.za's own count says 76,060 of 76,076 listings publish an odometer at all.
Does this cover motorcycles and commercial vehicles?
Commercial vehicles yes, properly: 16,886 of the listings are commercial, including 9,071 double-cab bakkies, 4,306 single-cab bakkies, 1,474 buses and minibuses, 755 panel vans and 351 dropsides, and each of those body types was measured returning full rows separately. Motorcycles are a thin surface on this site and the number is honest: switching bikes on moves the total from 76,076 to 76,125, so Cars.co.za is listing 49 bikes. They parse fine, but a motorcycle's detail record comes back with an empty manufacturer spec table, because Cars.co.za publishes none for them, and the response says so.
What does Cars.co.za not publish?
No VIN, no registration or plate number and no service-history document anywhere on these surfaces. No bidding or auction surface, because it is a fixed-price marketplace. No days-on-market figure, though the single-listing record does carry the date the car was listed. No phone number on a search row, as above. None of those are returned as empty handles — the fields simply do not exist in the response.
What is the Cars.co.za API?
Cars.co.za API is a ReefAPI endpoint group for south african car marketplace: 76,076 new and used listings from 1,710 dealerships and 211 private sellers, with price in rand, odometer, full spec table, deal grade and the selling dealer's address, geo and rating. It returns live JSON through POST requests under /cars-co-za/v1.
Is the Cars.co.za API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Cars.co.za calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Cars.co.za login or account?
No login to Cars.co.za 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 Cars.co.za 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 Cars.co.za API use?
Cars.co.za actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.