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

# Location Autocomplete

> Resolve a town, area or postcode prefix to Gumtree locations in the UK, Australia or South Africa.

Resolve a place name or postcode prefix to the locations Gumtree knows. Pass a
result to [`/search`](https://docs.scrapebadger.com/api-reference/endpoint/gumtree/search) as `location`:
its `name` (a town) or a postcode on `uk`, its numeric `id` on `au`, its ref
`id` on `za`. UK and South African results carry coordinates.

**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*

Town, area or postcode prefix — at least 2 characters, e.g. `manch`, `leed`
or `SW1A` (`uk`), `sydney` (`au`), `pret` (`za`).

## Response

**market** `string`

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

**query** `string`

Echo of the requested prefix.

**result\_count** `integer`

Number of locations.

**locations** `LocationSuggestion[]`

Matching locations.

**LocationSuggestion**

**id** `integer | string`

Gumtree location id — the `/search``location` on `au` (a number) and `za` (a ref like `pfw8k`).

**name** `string`

e.g. `Leeds City Centre, West Yorkshire`, `Sydney Region, NSW`, `Western Cape > Cape Town`.

**type** `string`

`uk`: `location`, `outcode` or `postcode`. `au`: `region`, `area` or `postcode`. `za`: `region` (a province) or `area`.

**latitude** `number`

`uk` and `za`.

**longitude** `number`

`uk` and `za`.

## Example

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

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

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

res = requests.get(
    "https://scrapebadger.com/v1/gumtree/locations/autocomplete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "leed"},
)
locations = res.json()["locations"]
```

```json Response theme={null}
{
  "market": "uk",
  "query": "leed",
  "result_count": 2,
  "locations": [
    {
      "id": 10000360,
      "name": "Leeds",
      "type": "location",
      "latitude": 53.808019,
      "longitude": -1.541784
    },
    {
      "id": 52026,
      "name": "Leeds City Centre, West Yorkshire",
      "type": "location",
      "latitude": 53.797899,
      "longitude": -1.548119
    }
  ]
}
```

### South Africa

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

```json Response (abridged) theme={null}
{
  "market": "za",
  "query": "cape town",
  "result_count": 10,
  "locations": [
    {
      "id": "pfw8k",
      "name": "Western Cape > Cape Town",
      "type": "area",
      "latitude": -33.81945,
      "longitude": 18.48657
    },
    {
      "id": "zcdv5",
      "name": "Western Cape > Cape Town > Cape Town City Centre",
      "type": "area",
      "latitude": -33.92427,
      "longitude": 18.4187
    }
  ]
}
```

Pass the `id` (`pfw8k`) to `/search?market=za` as `location`. gumtree.co.za
matches on the first 12 characters of the query.

### Australia

On `au`, `query=sydney` returns `Sydney Region, NSW` (`3003435`), `Inner
Sydney, NSW` (`3003771`), postcodes such as `North Sydney 2060, NSW` and more.
Pass the `id` to `/search` as `location`.

> [!TIP]
>
> On `uk`, `/search` also takes a full UK postcode directly as `location`
> (`location=SW1A 1AA&distance=2`), so you only need this endpoint to resolve
> partial input or to show the user a choice.

## Errors

| Status | Meaning |
| - | - |
| `422` | `query` is shorter than 2 characters, or Gumtree temporarily refused the request. **Not billed** — retry the latter shortly. |


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