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

# Get Search Filters

> The filters, sort orders and radius options Gumtree offers for a category, each value with its live result count.

List every filter Gumtree offers for a category — make, model, fuel type,
mileage range, bedrooms, job type and so on — with a **live result count** per
value, plus the available sort orders and search radii. Feed a filter's `key`
and an option's `value` straight back into
[`/search`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search) as `filters=key:value`.
Filter keys are each site's own, so always ask with the `market` you will
search.

**Credits:** 5

## Authorization

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

Your ScrapeBadger API key.

## Query Parameters

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

`uk` (gumtree.com), `au` (gumtree.com.au) or `za` (gumtree.co.za).

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

`uk`: category slug, e.g. `cars`, `property-to-rent`, `jobs`. `au`: numeric
category id, e.g. `18320` (cars). `za`: category ref, e.g. `p6dnh` (Cars &
Bakkies). Filters are category-specific, so pass the category you intend to
search.

**location** `string`

`uk`: location slug, town name or UK postcode. `au`: numeric location id.
`za`: location ref, e.g. `dkp8y` (Gauteng). Scopes the counts. Omit for the
whole country.

**query** `string`

Optional keywords to scope the counts.

**filters** `string`

`za` only: filters already applied, as `key:value` pairs. The counts follow
them — e.g. `make:toyota` narrows the `model` filter to Toyota's models
(`HILUX`, `COROLLA` …).

## Response

**market** `string`

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

**category** `string`

Category slug (`uk`), id (`au`) or ref (`za`).

**category\_name** `string`

e.g. `Cars`.

**total\_results** `integer`

Matching listings before any filter.

**filters** `SearchFilter[]`

Filters for the category.

**SearchFilter**

**key** `string`

Filter key for `filters=key:value`, e.g. `vehicle_make`.

**label** `string`

e.g. `Make`.

**type** `string`

`enum`, `multiple_selection`, `enum_range`, `range`, `range_freeform` or `boolean`.

**min\_key** `string`

Range filters: the lower-bound key when Gumtree names it explicitly (e.g. `min_price`). Otherwise it is `min_` + `key`.

**max\_key** `string`

Range filters: the upper-bound key, likewise `max_` + `key` when null.

**options** `FilterOption[]`

`label`, `value`, `count` — `value` is what `/search` takes. Empty for range filters.

**min\_options** `FilterOption[]`

Range filters: the lower bounds Gumtree offers.

**max\_options** `FilterOption[]`

Range filters: the upper bounds Gumtree offers.

**sort\_options** `SortOption[]`

Sort orders Gumtree offers for the category — `value`, `label`.

**distance\_options** `number[]`

Search radius values in miles (`uk`). Empty for `au` (any km value up to `1000` is accepted) and `za` (no radius search).

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

Sub-categories with counts — `id`, `name`, `slug`, `count`.

## Example

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

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

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

res = requests.get(
    "https://scrapebadger.com/v1/gumtree/search/filters",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"category": "cars"},
)
filters = res.json()["filters"]
```

```json Response theme={null}
{
  "market": "uk",
  "category": "cars",
  "category_name": "Cars",
  "total_results": 139812,
  "filters": [
    {
      "key": "vehicle_make",
      "label": "Make",
      "type": "enum",
      "min_key": null,
      "max_key": null,
      "options": [
        { "label": "Abarth", "value": "abarth", "count": 265 },
        { "label": "AC", "value": "ac", "count": 1 },
        { "label": "Aixam", "value": "aixam", "count": 1 }
      ],
      "min_options": [],
      "max_options": []
    },
    {
      "key": "vehicle_mileage",
      "label": "Mileage",
      "type": "enum_range",
      "min_key": null,
      "max_key": null,
      "options": [],
      "min_options": [
        { "label": "0 miles", "value": "0", "count": null },
        { "label": "10,000 miles", "value": "10000", "count": null },
        { "label": "50,000 miles", "value": "50000", "count": null }
      ],
      "max_options": [
        { "label": "1,000 miles", "value": "1000", "count": null },
        { "label": "10,000 miles", "value": "10000", "count": null }
      ]
    }
  ],
  "sort_options": [
    { "value": "relevance", "label": "Most relevant first" },
    { "value": "date", "label": "Most recent first" },
    { "value": "price_asc", "label": "Price: Low to High" },
    { "value": "price_desc", "label": "Price: High to Low" },
    { "value": "distance", "label": "Nearest first" }
  ],
  "distance_options": [1.0, 3.0, 5.0, 10.0, 15.0, 30.0, 50.0, 75.0, 100.0, 1000.0],
  "category_facets": []
}
```

> [!NOTE]
>
> `sort_options` values are the ones [`/search`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search)
> accepts as `sort` — pass them straight back.

### Using a filter in `/search`

| Filter `type` | Pass to `/search` as |
| - | - |
| `enum`, `multiple_selection` | `filters=vehicle_make:bmw` — repeat the key for several values: `vehicle_make:bmw,vehicle_make:audi` |
| `enum_range`, `range` | `filters=min_vehicle_mileage:10000,max_vehicle_mileage:50000` (`min_` / `max_` + `key`, or the explicit `min_key` / `max_key`) |

`price`, `seller_type`, `photos_filter` and `urgent_filter` also appear in this
list for `uk`; on `/search` use the dedicated `min_price` / `max_price`,
`seller_type`, `with_photos` and `urgent_only` parameters for them.

### South Africa

With a make applied, the counts — and the models listed — narrow to that make
(Toyota cars in Gauteng). The `make` filter itself keeps every make's count so
you can switch:

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/search/filters?market=za&category=p6dnh&location=dkp8y&filters=make:toyota" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response (abridged) theme={null}
{
  "market": "za",
  "category": "p6dnh",
  "category_name": "Cars & Bakkies",
  "total_results": 429,
  "filters": [
    {
      "key": "make",
      "label": "Make",
      "type": "enum",
      "options": [
        { "label": "Toyota", "value": "TOYOTA", "count": 429 },
        { "label": "Volkswagen", "value": "VOLKSWAGEN", "count": 407 }
      ]
    },
    {
      "key": "model",
      "label": "Model",
      "type": "enum",
      "options": [
        { "label": "Hilux", "value": "HILUX", "count": 98 },
        { "label": "Corolla", "value": "COROLLA", "count": 58 }
      ]
    },
    {
      "key": "year",
      "label": "Year",
      "type": "range_freeform",
      "min_key": "min_year",
      "max_key": "max_year"
    }
  ],
  "sort_options": [
    { "value": "relevance", "label": "Best match" },
    { "value": "date", "label": "Most recent" },
    { "value": "price_asc", "label": "Lowest price" },
    { "value": "price_desc", "label": "Highest price" }
  ],
  "distance_options": []
}
```

South African keys on Cars & Bakkies (`p6dnh`): `make`, `model`, `bodyType`,
`driveType`, `transmission`, `fuelType`, `colour`, and the ranges `year`
(`min_year` / `max_year`) and `mileageKm` (`min_mileageKm` / `max_mileageKm`).
Each key takes one value. Price and seller type are the `/search` parameters
`min_price` / `max_price` and `seller_type`, so they are not listed here.

### Australia

Australian keys are namespaced by category, e.g. for cars (`18320`):
`cars.carmake_s` (make), `cars.carbodytype_s`, `cars.caryear_i` (a `range` —
`min_cars.caryear_i` / `max_cars.caryear_i`), `cars.fueltype_s`,
`cars.cartransmission_s`, `cars.forsaleby_s` (private or dealer) and
`priceType` (`FIXED`, `NEGOTIABLE` …).

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/search/filters?market=au&category=18320" \
  -H "X-API-Key: YOUR_API_KEY"
```

> [!TIP]
>
> Use this endpoint to size a search before paging it: the per-value counts
> tell you which filters bring a result set under the 50-page ceiling of
> `/search`.

## Errors

| Status | Meaning |
| - | - |
| `400` | An unknown `category` or `location` id or ref, malformed `filters`, or `filters` with `market=uk`. |
| `422` | Gumtree temporarily refused the request — **not billed**. Retry shortly. |


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