Scraper API for Gumtree
The ScrapeBadger Gumtree API turns three Gumtree classifieds sites —gumtree.com (UK), gumtree.com.au (Australia) and gumtree.co.za (South
Africa) — into one clean JSON feed: keyword and category search with location,
radius and category-specific filters, filter discovery with live counts, full
listing detail (every attribute, the full vehicle spec for cars, the seller’s
profile and similar ads), a seller’s other listings, search and location
autocomplete, and the category and location trees.
Every endpoint takes a market parameter — uk (the default), au or za —
so existing UK integrations keep working unchanged.
All endpoints are
GET, live under https://scrapebadger.com/v1/gumtree/*,
and authenticate with the X-API-Key header. Credits are charged per request
(see the table below) and reported on the X-Credits-Used response header.Features
- Three markets, one schema — UK, Australia and South Africa share the same
response models; every top-level response carries its
market, and prices come in the market’scurrency(GBP, AUD, ZAR). A field a site does not publish is simplynullthere. - Every vertical — For Sale, Motors, Property, Jobs, Services, Pets and Community. 25 (UK) or 24 (AU) listings per search page, up to 50 pages; 20 (ZA) per page across the first 375 matches.
- Location search — UK
locationtakes a town slug, a town name or a full UK postcode (SW1A 1AA) with adistancein miles; Australia takes a numeric location id with adistancein km; South Africa takes a province or town ref such asdkp8y(Gauteng). - Category filters with live counts —
/search/filterslists every filter Gumtree offers for a category (make, model, fuel type, mileage or year range, bedrooms …) with the result count per value; pass them back to/searchasfilters=key:value. - Full vehicle spec on Motors listings — make, model, year, mileage, fuel, transmission, body type and engine; the UK adds MPG, CO2, insurance group, previous keepers and the history-check flags, Australia adds variant, odometer, VIN and rego where the seller shows them.
- Seller profile — private or trade, rating, verification (UK; ZA lists the identity and mobile-number checks), posting since, member since (AU, ZA), live listing counts, and the masked phone number (UK).
- Promotion flags —
is_featured,is_urgent,is_bumped_up,is_standoutandfavourite_countwhere the site publishes them. - Dates in both forms — every timestamp ships as Unix seconds (
*_utc) and ISO 8601 (*_at). Listing detail separatescreated_at(first posted) fromposted_at(moves on a bump). - No silent broadening — an unknown category or location id, a parameter a
market does not support, or a filter the site would quietly drop is a
400, never a search that silently ran across the whole country.
Phone numbers are masked. Only the masked form Gumtree shows on the public
listing page is returned (e.g.
0794997XXXX in the UK; Australia and South
Africa show none). Full numbers are never returned.Markets
Passmarket on every request. The three sites are separate platforms: category,
location and listing ids from one market mean nothing in another. List them with
/markets.
Listing ids
- UK and Australia — the ~10-digit number at the end of a listing URL, e.g.
1803293391(UK) or1344981847(AU). - South Africa — the listing ref at the end of a
gumtree.co.za/listing/<ref>URL, e.g.ls26bvmcpnsqmz7l9jz.
Credit Costs
Every market costs the same. gumtree.com.au puts its search behind a
JavaScript challenge; ScrapeBadger clears it for you, so Australian calls
are billed at the price above and answer in ~2–5 seconds, like UK and South
African ones.
Quickstart
Typical workflow
- Pick a market —
uk,auorza. Use the samemarketon every call in the workflow. - Pick a category —
/categoriesor/autocompletegive you theslug(UK:cars,property-to-rent…) orid(AU:18320…; ZA:p6dnh…). - Pick a location (optional) —
/locations/autocompleteor/locations. Without one, the search covers the whole country. - Discover its filters —
/search/filtersreturns each filter’skeyand values with live counts. - Search —
/searchwithcategory,location(+distancein the UK and Australia), price band andfilters. - Enrich —
/listings/{id}for the full description, attributes and seller, and/listings/{id}/seller-listingsfor everything else that seller has listed.
Limits
- 50 pages per result set (UK, AU). gumtree.co.za pages through only the
first 375 matches (19 pages of 20), while
total_resultsstill reports the full count. To go deeper, narrow by sub-category, location anddistance, price band or filters. A page past the end comes back empty and is not billed. - UK price filters need a category.
min_price/max_priceare refused withcategory=allin the UK, where Gumtree would ignore them. - Market-specific parameters.
urgent_onlyandwith_photosare UK only.distanceis UK (miles) and Australia (km).seller_typeis UK and South Africa — in Australia pass it as a filter (e.g.cars.forsaleby_s:ownr).sort=distanceneeds the UK, or Australia with alocation. Anything else is a400. - Featured ads are pinned. Gumtree places paid featured ads
(
is_featured) above the chosen sort order — up to 5 in the UK, up to 6 in Australia. - Seller listings are keyed by a listing. Pass any listing id of the seller
to
/listings/{id}/seller-listings; there is no separate seller lookup.
Errors
Run this asynchronously
Calls on this API can run in the background, so you don’t hold a connection open while they work. Add one of these to the call:ScrapeBadger is an independent tool and is not affiliated with, endorsed by, or sponsored by Gumtree. “Gumtree” is a trademark of its respective owner, used here only to describe the platform this scraper is designed to work with.

