Skip to main content

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’s currency (GBP, AUD, ZAR). A field a site does not publish is simply null there.
  • 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 location takes a town slug, a town name or a full UK postcode (SW1A 1AA) with a distance in miles; Australia takes a numeric location id with a distance in km; South Africa takes a province or town ref such as dkp8y (Gauteng).
  • Category filters with live counts — /search/filters lists 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 /search as filters=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_standout and favourite_count where the site publishes them.
  • Dates in both forms — every timestamp ships as Unix seconds (*_utc) and ISO 8601 (*_at). Listing detail separates created_at (first posted) from posted_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

Pass market 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.
For au and za, get ids from /categories, /locations and /locations/autocomplete with the same market. Omit location to search the whole country.

Listing ids

  • UK and Australia — the ~10-digit number at the end of a listing URL, e.g. 1803293391 (UK) or 1344981847 (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

  1. Pick a market — uk, au or za. Use the same market on every call in the workflow.
  2. Pick a category — /categories or /autocomplete give you the slug (UK: cars, property-to-rent …) or id (AU: 18320 …; ZA: p6dnh …).
  3. Pick a location (optional) — /locations/autocomplete or /locations. Without one, the search covers the whole country.
  4. Discover its filters — /search/filters returns each filter’s key and values with live counts.
  5. Search — /search with category, location (+ distance in the UK and Australia), price band and filters.
  6. Enrich — /listings/{id} for the full description, attributes and seller, and /listings/{id}/seller-listings for 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_results still reports the full count. To go deeper, narrow by sub-category, location and distance, 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_price are refused with category=all in the UK, where Gumtree would ignore them.
  • Market-specific parameters. urgent_only and with_photos are UK only. distance is UK (miles) and Australia (km). seller_type is UK and South Africa — in Australia pass it as a filter (e.g. cars.forsaleby_s:ownr). sort=distance needs the UK, or Australia with a location. Anything else is a 400.
  • 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

The reference endpoints — autocomplete, location autocomplete and categories (and locations in the UK and South Africa) — cost 2 credits each. Use them to build the right category and location before spending credits on a search.

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:
An async call is billed once, when it completes. See Async requests and webhooks for webhooks, signatures and the SDK helpers.
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.