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

# Search Listings

> Search Gumtree classified ads in the UK, Australia or South Africa by keyword, category, location and radius, price band, seller type and category-specific filters.

Search Gumtree listings across every vertical — For Sale, Motors, Property,
Jobs, Services, Pets and Community — on `gumtree.com` (UK), `gumtree.com.au`
(Australia) or `gumtree.co.za` (South Africa). Returns 25 (UK) or 24 (AU)
listings per page plus any pinned featured ads, up to 50 pages, or 20 (ZA) per
page across the first 375 matches.

**Credits:** 5

## Authorization

**X-API-Key** `string` *required*

Your ScrapeBadger API key.

## Query Parameters

**market** `string` (default: uk)

Which Gumtree: `uk` (gumtree.com, GBP), `au` (gumtree.com.au, AUD) or `za`
(gumtree.co.za, ZAR). Separate sites — category, location and listing ids
from one market mean nothing in another.

**query** `string`

Search keywords, e.g. `mountain bike`. Optional — omit it to browse a whole
category.

**category** `string` (default: all)

* `uk`: category slug, e.g. `cars`, `for-sale`, `property-to-rent`, `jobs`,
  `pets`, `bicycles`.
* `au`: numeric category id, e.g. `18320` (cars), `18560` (bicycles).
* `za`: category ref, e.g. `p6dnh` (Cars & Bakkies), `l4dq6` (Vehicles).

Browse the tree with
[`/categories`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/list-categories) for the same
`market`. An unknown id or ref is a `400`.

**location** `string`

Omit to search the whole country.

* `uk`: location slug (`london`, `manchester`), town name or full UK postcode
  (`SW1A 1AA`).
* `au`: numeric location id, e.g. `3003435` (Sydney Region).
* `za`: location ref, e.g. `dkp8y` (Gauteng), `pfw8k` (Cape Town).

Resolve a place with
[`/locations/autocomplete`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/location-autocomplete).
An unknown location is a `400` — the sites would otherwise silently search
the whole country.

**distance** `number`

Radius around `location`, greater than `0` and up to `1000`: miles (`uk`) or
km (`au`, needs a `location`). Not supported for `za`.

**min\_price** `integer`

Minimum price in the market's currency. `uk`: needs a `category` other than
`all`.

**max\_price** `integer`

Maximum price in the market's currency. `uk`: needs a `category` other than
`all`.

**sort** `string` (default: relevance)

Result ordering. One of `relevance`, `date`, `price_asc`, `price_desc`,
`distance`. `distance` needs `uk`, or `au` with a `location`.

**seller\_type** `string`

`private` or `trade`. `trade` covers dealers, letting agents and recruiters.
`uk` and `za` only — on `au` pass it as a filter instead (e.g.
`cars.forsaleby_s:ownr`).

**urgent\_only** `boolean` (default: false)

`uk` only: only ads the seller marked urgent.

**with\_photos** `boolean` (default: false)

`uk` only: only ads with photos.

**filters** `string`

Category-specific filters as comma-separated `key:value` pairs. Range filters
take `min_<key>:<value>` / `max_<key>:<value>`. Keys differ per market —
discover them, with their values, from
[`/search/filters`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search-filters) for the
same `market` and `category`:

* `uk`: `vehicle_make:bmw,vehicle_fuel_type:petrol,min_vehicle_mileage:10000`.
  Repeat a key to select several values (`vehicle_make:bmw,vehicle_make:audi`).
* `au`: `cars.carmake_s:toyota,min_cars.caryear_i:2015,priceType:NEGOTIABLE`.
* `za`: `make:toyota,model:hilux,fuelType:diesel,max_mileageKm:100000,min_year:2015`
  — on Cars & Bakkies: `make`, `model`, `bodyType`, `driveType`,
  `transmission`, `fuelType`, `colour`, and the ranges `year` and
  `mileageKm`. Values are case-insensitive (`toyota` = `TOYOTA`). One value
  per key. A key gumtree.co.za does not know is a `400`; a value it does not
  know matches nothing.

**page** `integer` (default: 1)

Result page, `1`–`50` (`za`: results past the 375th are not reachable; such
a page comes back empty).

## Response

**market** `string`

`uk`, `au` or `za`.

**query** `string`

Echo of the requested keywords.

**category** `string`

Category the search ran in — slug (`uk`), id (`au`) or ref (`za`).

**category\_name** `string`

e.g. `Cars`.

**category\_id** `integer | string`

Gumtree category id — an integer on `uk` / `au`, a ref string on `za` (e.g. `p6dnh`).

**location** `string`

Location slug, postcode, id or ref searched.

**location\_name** `string`

e.g. `United Kingdom`, `Sydney Region`.

**distance** `number`

Radius (miles `uk`, km `au`), when one was applied.

**sort** `string`

The sort that was applied.

**page** `integer`

The page returned.

**total\_pages** `integer`

Pages available for this search (at most `50`; `za`: at most `19`).

**total\_results** `integer`

Total matching listings Gumtree reports.

**result\_count** `integer`

Listings on this page, featured ads included.

**currency** `string`

`GBP`, `AUD` or `ZAR`.

**url** `string`

The Gumtree search URL equivalent to this request.

**category\_facets** `CategoryFacet[]`

Sub-categories of the result set with counts — `id`, `name`, `slug`, `count`.
Feed a `slug` (`uk`) or `id` (`au`, `za` — a ref like `p6dnh` there) back in
as `category` to drill down.

**listings** `ListingSummary[]`

Listing cards.

**ListingSummary**

**id** `string`

Listing id — use it for `/listings/{listing_id}`. `za`: the listing ref, e.g. `ls26bvmcpnsqmz7l9jz`.

**short\_id** `string`

Always `null` (the old gumtree.co.za short id no longer exists).

**title** `string`

**url** `string`

**description** `string`

Gumtree's short description.

**price** `number`

Numeric price in `currency`; `null` for negotiable or contact-for-price ads.

**price\_text** `string`

Price as shown, e.g. `£1,850.00pm`, `$17,990`, `R190,000`, `Negotiable`.

**price\_frequency** `string`

`pm` / `pw` for rentals.

**price\_type** `string`

`au`: `FIXED`, `NEGOTIABLE`, `CONTACT_ME`, `FREE`, `SWAP_TRADE` … `za`: `ASKING_PRICE`, `POA` …

**currency** `string`

`GBP`, `AUD` or `ZAR`.

**location** `string`

e.g. `Penkridge, Staffordshire`.

**location\_id** `string`

**postcode** `string`

**latitude** `number`

**longitude** `number`

**distance\_text** `string`

e.g. `13 miles` (`uk`) or `4 km` (`au`) from the search location.

**distance\_miles** `number`

**category\_id** `integer | string`

Integer on `uk` / `au`, ref string on `za`.

**category\_name** `string`

**category\_ids** `(integer | string)[]`

Root-to-leaf category ids (refs on `za`).

**image\_url** `string`

**image\_urls** `string[]`

**image\_count** `integer`

**posted\_text** `string`

Relative age as shown, e.g. `3 days ago`.

**posted\_utc** `number`

Unix seconds.

**posted\_at** `string`

ISO 8601 UTC.

**status** `string`

e.g. `LIVE`.

**seller\_type** `string`

`Private`, `Trade` or `Agency` (`au` motors: e.g. `Dealer used`).

**seller\_id** `string`

**seller\_name** `string`

`au` / `za`: the seller's display name.

**account\_id** `string`

**is\_pro\_seller** `boolean`

**is\_featured** `boolean`

Paid top-slot ad.

**is\_urgent** `boolean`

**is\_bumped\_up** `boolean`

**is\_standout** `boolean`

**is\_premium** `boolean`

**has\_video** `boolean`

**supports\_shipping** `boolean`

**favourite\_count** `integer`

**seller\_skills** `string[]`

Services listings only.

**attributes** `Attribute[]`

Category attributes — `key`, `label`, `value`, `unit`. Motors listings
carry the vehicle spec (make, model, year, mileage, fuel, engine; `uk`
adds MPG, CO2, insurance group and history-check flags). Keys are each
site's own, e.g. `vehicle_mileage` (`uk`), `carmileageinkms` (`au`),
`mileageKm` (`za`).

## Example

```bash cURL theme={null}
curl "https://scrapebadger.com/v1/gumtree/search?category=cars" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://scrapebadger.com/v1/gumtree/search?" +
    new URLSearchParams({ category: "cars" }),
  { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const data = await res.json();
```

```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"},
)
data = res.json()
```

```json Response theme={null}
{
  "market": "uk",
  "query": null,
  "category": "cars",
  "category_name": "Cars",
  "category_id": 9311,
  "location": "uk",
  "location_name": "United Kingdom",
  "distance": null,
  "sort": "relevance",
  "page": 1,
  "total_pages": 50,
  "total_results": 139812,
  "result_count": 30,
  "currency": "GBP",
  "listings": [
    {
      "id": "1802409381",
      "title": "Ford, RANGER, Pick Up, 2024, Automatic, 1996 (cc)",
      "url": "https://www.gumtree.com/p/ford/ford-ranger-pick-up-2024-automatic-1996-cc-/1802409381",
      "description": "2024 Ford Ranger Automatic – NO VAT – Only 11,400 Miles\n\nVery clean, low-mileage example of a 2024 Ford Ranger with just 11,400 miles from new...",
      "price": 29000.0,
      "price_text": "£29,000.00",
      "price_frequency": null,
      "currency": "GBP",
      "location": "Penkridge, Staffordshire",
      "location_id": "11002225",
      "postcode": "ST195DU",
      "latitude": 52.7257,
      "longitude": -2.10523,
      "category_id": 10306,
      "category_name": "Ford",
      "category_ids": [2551, 9311, 10306],
      "image_url": "https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/c77d793ecce84e13a9_a54724b51d3e/86",
      "image_count": 17,
      "posted_text": "4 days ago",
      "posted_utc": 1791395043.988,
      "posted_at": "2026-10-07T17:44:03.988000Z",
      "status": "LIVE",
      "seller_type": "Private",
      "seller_id": "96740710",
      "is_pro_seller": false,
      "is_featured": true,
      "is_urgent": true,
      "is_bumped_up": false,
      "is_standout": false,
      "favourite_count": 1,
      "attributes": [
        { "key": "vehicle_make", "label": "Make", "value": "Ford", "unit": null },
        { "key": "vehicle_model", "label": "Model", "value": "RANGER", "unit": null },
        { "key": "vehicle_registration_year", "label": "Year", "value": "2024", "unit": null },
        { "key": "vehicle_mileage", "label": "Mileage", "value": "11400", "unit": "miles" },
        { "key": "vehicle_fuel_type", "label": "Fuel type", "value": "Diesel", "unit": null },
        { "key": "vehicle_engine_power", "label": "Engine Power", "value": "205", "unit": "bhp" },
        { "key": "vehicle_not_writeoff", "label": "Not written-off", "value": "true", "unit": null },
        { "key": "vehicle_previous_keepers", "label": "Previous Keepers", "value": "4", "unit": null }
      ]
    }
  ],
  "category_facets": [],
  "url": "https://www.gumtree.com/search?search_category=cars&search_location=uk"
}
```

## Search behaviour

> [!NOTE]
>
> **UK price filters need a category.** gumtree.com ignores `min_price` /
> `max_price` when `category` is `all`, so that combination is a `400` — pick a
> category (`for-sale`, `cars`, `bicycles` …) to filter by price.

> [!NOTE]
>
> Gumtree pins **paid featured ads** (`is_featured: true`) above the chosen
> sort order — up to 5 in the UK and up to 6 in Australia. Skip them if you
> need a strict date or price ordering.

> [!WARNING]
>
> A result set holds at most **50 pages** (`za`: the first 375 matches, 19
> pages), whatever `total_results` reports. To
> collect more, narrow the search — by sub-category (`category_facets`),
> location and `distance`, price band, or
> [`filters`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search-filters). A page past the
> end comes back with no listings and is not billed.

### Market support

| Parameter | `uk` | `au` | `za` |
| - | - | - | - |
| `category` / `location` | slug / slug or postcode | numeric id | ref (`p6dnh` / `dkp8y`) |
| `distance` | miles | km (needs `location`) | — |
| `seller_type` | ✓ | as a filter | ✓ |
| `urgent_only`, `with_photos` | ✓ | — | — |
| `sort=distance` | ✓ | with `location` | — |
| Listings per page | 25 + featured | 24 + up to 6 featured | 20 (first 375 matches) |

A parameter a market does not support is a `400`, not silently ignored.

### Postcode radius

Pass a full UK postcode as `location` with a `distance` in miles:

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/search?query=sofa&category=for-sale&location=SW1A%201AA&distance=2" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Category filters

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/search?category=cars&filters=vehicle_make:bmw,vehicle_fuel_type:petrol,min_vehicle_mileage:10000" \
  -H "X-API-Key: YOUR_API_KEY"
```

Range filters (`type: enum_range`) take `min_` / `max_` + the filter key, e.g.
`min_vehicle_mileage:10000,max_vehicle_mileage:50000`. List every key and value
for a category with
[`/search/filters`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search-filters).

### South Africa

Petrol Toyotas in Gauteng between R50,000 and R300,000, cheapest first
(`p6dnh` = Cars & Bakkies, `dkp8y` = Gauteng) — 241 results on 2026-10-13:

```bash theme={null}
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"
```

Toyotas in Gauteng, newest first
(`market=za&category=p6dnh&location=dkp8y&filters=make:toyota&sort=date`),
abridged:

```json theme={null}
{
  "market": "za",
  "category": "p6dnh",
  "category_name": "Cars & Bakkies",
  "category_id": "p6dnh",
  "location": "dkp8y",
  "location_name": "Gauteng",
  "sort": "date",
  "page": 1,
  "total_pages": 19,
  "total_results": 429,
  "result_count": 20,
  "currency": "ZAR",
  "listings": [
    {
      "id": "ls26bvmcpnsqmz7l9jz",
      "title": "Toyota Yaris",
      "url": "https://www.gumtree.co.za/listing/ls26bvmcpnsqmz7l9jz",
      "description": "2018 Toyota Yaris 1.5XS CVT Automatic 85000km FSH with Toyota (service books including all...",
      "price": 190000.0,
      "price_text": "R190,000",
      "price_type": "ASKING_PRICE",
      "currency": "ZAR",
      "location": "Weltevreden Park",
      "location_id": "mxm68",
      "category_id": "p6dnh",
      "category_ids": ["kyzkk", "l4dq6", "p6dnh"],
      "image_count": 1,
      "posted_at": "2026-10-13T17:34:24.365000Z",
      "seller_id": "s16zcgy0ntjnvg2",
      "seller_name": "Thanuj",
      "attributes": [
        { "key": "mileageKm", "label": "Kilometres", "value": "85000", "unit": null },
        { "key": "transmission", "label": "Transmission", "value": "Automatic", "unit": null },
        { "key": "fuelType", "label": "Fuel Type", "value": "Petrol", "unit": null }
      ]
    }
  ],
  "url": "https://www.gumtree.co.za/search"
}
```

`total_results` is the full count, but gumtree.co.za only pages through the
first 375 matches: `total_pages` is at most `19`.

### Australia

Mountain bikes in the Sydney Region (`18560` = Bicycles, `3003435` = Sydney
Region), within 25 km:

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/search?market=au&query=mountain%20bike&category=18560&location=3003435&distance=25" \
  -H "X-API-Key: YOUR_API_KEY"
```

A listing card from an Australian cars search (`market=au&category=18320`),
abridged:

```json theme={null}
{
  "id": "1344981847",
  "title": "2018 Holden Commodore RS ZB",
  "url": "https://www.gumtree.com.au/web/listing/cars-vans-utes/1344981847",
  "price": 16990.0,
  "price_text": "$16,990",
  "price_type": "FIXED",
  "currency": "AUD",
  "location": "Wanneroo Area, WA",
  "category_id": 18320,
  "seller_type": "Dealer used",
  "is_featured": false,
  "attributes": [
    { "key": "carmileageinkms", "label": null, "value": "89168 km", "unit": null },
    { "key": "cartransmission", "label": null, "value": "Auto", "unit": null }
  ]
}
```

On `au`, sell-by and price type are filters: `filters=cars.forsaleby_s:ownr`
for private sellers, `priceType:NEGOTIABLE` for negotiable prices.

## Errors

| Status | Meaning |
| - | - |
| `400` | Malformed `filters` value; an unknown `category` or `location` id; a parameter the `market` does not support (see the table above); a `za` filter key gumtree.co.za does not know, or an old numeric `za` id; or `min_price` / `max_price` with `category=all` on `uk`. |
| `422` | Invalid parameter (e.g. `page` above 50), or Gumtree blocked the request. **Not billed**. |
| `503` | Gumtree's origin or transport is temporarily unavailable. **Not billed**. Wait for the `Retry-After` interval (currently 60 seconds) before retrying. |


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