> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gumtree Scraper by ScrapeBadger — Overview

> Search Gumtree classifieds in the UK (gumtree.com), Australia (gumtree.com.au) and South Africa (gumtree.co.za) by keyword, category, location and filters, and pull full listings with vehicle spec, seller profile and similar ads — no Gumtree account required.

## 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.

> [!NOTE]
>
> 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`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/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.

> [!NOTE]
>
> **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`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-markets).

| `market` | Country | Domain | Currency | `category` / `location` | `distance` | Results per page |
| - | - | - | - | - | - | - |
| `uk` (default) | United Kingdom | gumtree.com | GBP | Slugs — `cars`, `london`, or a UK postcode | miles | 25 + featured |
| `au` | Australia | gumtree.com.au | AUD | Numeric ids — `18320` (cars), `3003435` (Sydney Region) | km | 24 + up to 6 featured |
| `za` | South Africa | gumtree.co.za | ZAR | Refs — `p6dnh` (Cars & Bakkies), `dkp8y` (Gauteng) | not supported | 20 |

> [!TIP]
>
> For `au` and `za`, get ids from
> [`/categories`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-categories),
> [`/locations`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-locations) and
> [`/locations/autocomplete`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/location-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

| Endpoint | Path | Credits |
| - | - | - |
| Search listings | `GET /v1/gumtree/search` | 8 credits |
| Get search filters | `GET /v1/gumtree/search/filters` | 8 credits |
| Get listing | `GET /v1/gumtree/listings/{listing_id}` | 8 credits |
| Get seller listings | `GET /v1/gumtree/listings/{listing_id}/seller-listings` | 8 credits |
| Autocomplete | `GET /v1/gumtree/autocomplete` | 2 credits |
| Location autocomplete | `GET /v1/gumtree/locations/autocomplete` | 2 credits |
| List locations | `GET /v1/gumtree/locations` | 2 credits |
| List categories | `GET /v1/gumtree/categories` | 2 credits |
| List markets | `GET /v1/gumtree/markets` | 0 credits |
| Health | `GET /v1/gumtree/health` | 0 credits |

> [!NOTE]
>
> 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

```bash cURL theme={null}
curl "https://scrapebadger.com/v1/gumtree/search?category=cars&location=manchester&distance=30&filters=vehicle_make:bmw" \
  -H "X-API-Key: YOUR_API_KEY"

# South Africa: petrol Toyotas in Gauteng between R50,000 and R300,000
curl "https://scrapebadger.com/v1/gumtree/search?market=za&category=p6dnh&location=dkp8y&filters=make:toyota,fuelType:petrol&min_price=50000&max_price=300000&sort=price_asc" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://scrapebadger.com/v1/gumtree/search?" +
    new URLSearchParams({
      market: "au",
      query: "mountain bike",
      category: "18560",
      location: "3003435",
    }),
  { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const data = await res.json();
console.log(data.total_results, "listings in", data.currency);
```

```python Python theme={null}
import requests

res = requests.get(
    "https://scrapebadger.com/v1/gumtree/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "category": "cars",
        "location": "manchester",
        "distance": 30,
        "filters": "vehicle_make:bmw",
    },
)
print(res.json()["total_results"], "listings")
```

## 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`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-categories)
   or [`/autocomplete`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/autocomplete) give you
   the `slug` (UK: `cars`, `property-to-rent` …) or `id` (AU: `18320` …;
   ZA: `p6dnh` …).
3. **Pick a location** (optional) —
   [`/locations/autocomplete`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/location-autocomplete)
   or [`/locations`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-locations). Without
   one, the search covers the whole country.
4. **Discover its filters** —
   [`/search/filters`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search-filters) returns
   each filter's `key` and values with live counts.
5. **Search** — [`/search`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search) with
   `category`, `location` (+ `distance` in the UK and Australia), price band and
   `filters`.
6. **Enrich** — [`/listings/{id}`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/get-listing)
   for the full description, attributes and seller, and
   [`/listings/{id}/seller-listings`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/get-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

| Status | Meaning |
| - | - |
| `400` | Bad input the site would silently ignore — malformed `filters`, an unknown category or location id, a parameter the `market` does not support, a South African filter key or ref gumtree.co.za rejects (including the old numeric ids), or a listing id from another market. |
| `404` | Listing does not exist or has been removed. |
| `422` | Invalid parameter, or Gumtree temporarily refused the request. **Not billed** — retry the latter shortly. |

> [!TIP]
>
> 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:

| Add | What you get |
| - | - |
| `async=true` | The normal response if the call finishes within 25 s. Otherwise `202` with a `request_id`, which you poll at `GET /v1/requests/{request_id}` for free. |
| `callback_url=https://…` | `202` at once. When the call completes, the result is POSTed to your URL, signed with your webhook secret. |
| `Idempotency-Key: <your id>` header | A resent submit returns the first call instead of running it again. |

```bash theme={null}
curl -s "https://scrapebadger.com/v1/...?your=params&async=true" \
  -H "X-API-Key: $SCRAPEBADGER_API_KEY"
# 202 {"request_id": "…", "status": "running", …}, then:
curl -s "https://scrapebadger.com/v1/requests/REQUEST_ID" \
  -H "X-API-Key: $SCRAPEBADGER_API_KEY"
```

An async call is billed once, when it completes. See [Async requests and webhooks](https://docs.scrapebadger.com/long-running-requests.md) 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.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.