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

# Autocomplete

> Gumtree search-box keyword suggestions for a partial term, each with the categories it maps to.

Expand a partial search term into Gumtree's own search-box suggestions. Where
Gumtree attaches categories to a suggestion, they come back with their `slug`
(`uk`) or `id` (`au`; a ref like `p6dnh` on `za`), ready to pass to
[`/search`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search) as `category`.

**Credits:** 1

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

**query** `string` *required*

Partial search term, e.g. `sofa` or `iph`.

## Response

**market** `string`

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

**query** `string`

Echo of the requested term.

**result\_count** `integer`

Number of suggestions.

**suggestions** `Suggestion[]`

Suggestions.

**Suggestion**

**query** `string`

The suggested search term — feed straight into `/search`.

**highlighted** `string`

The term with the matched part highlighted as the site does it — `<em>` (`uk`) or `<strong>` (`au`); `null` on `za`.

**categories** `CategoryRef[]`

`id`, `name`, `slug` of the categories Gumtree suggests for the term. On `au` / `za` pass the `id` (a ref on `za`) to `/search` as `category`.

## Example

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

```javascript Node.js theme={null}
const res = await fetch(
  "https://scrapebadger.com/v1/gumtree/autocomplete?" +
    new URLSearchParams({ query: "sofa" }),
  { 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/autocomplete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "sofa"},
)
data = res.json()
```

```json Response theme={null}
{
  "market": "uk",
  "query": "sofa",
  "result_count": 10,
  "suggestions": [
    {
      "query": "sofa",
      "highlighted": "<em>sofa</em>",
      "categories": [
        { "id": 12494, "name": "Sofas & Couches", "slug": "sofas-couches" },
        { "id": 679, "name": "Sofa Beds & Futons", "slug": "sofa-beds-futons" }
      ]
    },
    { "query": "sofa bed", "highlighted": "<em>sofa</em> bed", "categories": [] },
    { "query": "sofa set", "highlighted": "<em>sofa</em> set", "categories": [] }
  ]
}
```

### South Africa

```bash theme={null}
curl "https://scrapebadger.com/v1/gumtree/autocomplete?market=za&query=toyota" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response (abridged) theme={null}
{
  "market": "za",
  "query": "toyota",
  "result_count": 5,
  "suggestions": [
    {
      "query": "Toyota",
      "highlighted": null,
      "categories": [{ "id": "p6dnh", "name": "Cars & Bakkies", "slug": null }]
    },
    {
      "query": "toyota",
      "highlighted": null,
      "categories": [{ "id": "kdtkk", "name": "Car Parts & Spares", "slug": null }]
    },
    {
      "query": "Toyota Hilux",
      "highlighted": null,
      "categories": [{ "id": "p6dnh", "name": "Cars & Bakkies", "slug": null }]
    }
  ]
}
```

> [!TIP]
>
> A suggestion's category `slug` is the cheapest way to find the right
> `category` for a search — e.g. `query=sofa&category=sofas-couches` — which
> also unlocks the price filters.


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