# Gumtree API guide



## Choose a Gumtree operation



Start with the object your task needs. The groups below use the current catalogue; open an endpoint to check accepted identifiers, filters, price and availability before retrieving.



### Products and categories



- [Gumtree categories](https://www.monocrawl.com/docs/endpoints/gumtree/categories) — The category tree, or one category's subtree.

- [Gumtree listing](https://www.monocrawl.com/docs/endpoints/gumtree/product) — One listing's page: description, price, category path, location, attributes, images, the seller's profile and the seller ids the seller routes take.

- [Gumtree similar listings](https://www.monocrawl.com/docs/endpoints/gumtree/product-similar) — Listings similar to one listing.



### Other operations



- [Gumtree category filters](https://www.monocrawl.com/docs/endpoints/gumtree/filters) — The filters a category offers, with their kinds, parameters and options.

- [Gumtree location lookup](https://www.monocrawl.com/docs/endpoints/gumtree/locations) — Location ids for a place name, with coordinates, for use in searches.

- [Gumtree nearest location](https://www.monocrawl.com/docs/endpoints/gumtree/locations-nearest) — The site's location record nearest to a coordinate.



### Search and discovery



- [Gumtree search](https://www.monocrawl.com/docs/endpoints/gumtree/search) — One page of Gumtree UK listings for a keyword: title, price, location, age, seller flags and URL.

- [Gumtree search suggestions](https://www.monocrawl.com/docs/endpoints/gumtree/search-suggestions) — Keyword suggestions for a partial search, each with the category it belongs to.

- [Gumtree trending searches](https://www.monocrawl.com/docs/endpoints/gumtree/trending) — The search terms trending on the site right now.



## Check fields and collection limits



Use the endpoint’s declared parameters and returned continuation. Filters from another platform do not automatically apply here. Preserve source identifiers, URLs and warnings; a successful page does not establish complete history. Published response schemas identify whether they come from a reviewed shaper or observed response shapes.



Agents can use `get_endpoint` for the current contract and `get_docs` with topic `platforms/gumtree` to read this page. The [coverage guide](https://www.monocrawl.com/docs/data-availability) explains nulls and partial results, and the [production guide](https://www.monocrawl.com/docs/production-checklist) covers budgets and recovery.



## Endpoint reference

## gumtree/categories

`GET /v1/gumtree/categories`

The category tree, or one category's subtree.

*Gumtree categories*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | no | Category id to return a subtree; omit for the whole tree — e.g. `9311` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/categories?id=9311" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "children": [],
  "count": 0,
  "id": "example",
  "name": "example",
  "parent_id": "example",
  "seo_name": "example",
  "slug": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/categories#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/categories.json)


## gumtree/filters

`GET /v1/gumtree/filters`

The filters a category offers, with their kinds, parameters and options.

*Gumtree category filters*

| Parameter | Required | Description |
| --- | --- | --- |
| `category` | yes | Category id — e.g. `9311` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/filters?category=9311" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "category_id": "example",
  "count": 0,
  "has_more": false,
  "items": [
    {
      "kind": "example",
      "label": "example",
      "max_param": "example",
      "min_param": "example",
      "name": "example",
      "options": [
        {}
      ]
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/filters#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/filters.json)


## gumtree/locations

`GET /v1/gumtree/locations`

Location ids for a place name, with coordinates, for use in searches.

*Gumtree location lookup*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Place name, outcode or postcode — e.g. `london` |
| `type` | no | location, outcode or postcode Accepted values: location, outcode, postcode. Case, spaces, hyphens and underscores are interchangeable. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/locations?query=london" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "id": "example",
      "kind": "example",
      "latitude": 0,
      "longitude": 0,
      "name": "example"
    }
  ],
  "query": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/locations#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/locations.json)


## gumtree/locations-nearest

`GET /v1/gumtree/locations-nearest`

The site's location record nearest to a coordinate.

*Gumtree nearest location*

| Parameter | Required | Description |
| --- | --- | --- |
| `latitude` | yes | Latitude — e.g. `51.5074` |
| `longitude` | yes | Longitude — e.g. `-0.1278` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/locations-nearest?latitude=51.5074&longitude=-0.1278" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "example",
  "kind": "example",
  "latitude": 0,
  "longitude": 0,
  "name": "example",
  "query": {
    "latitude": 0,
    "longitude": 0
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/locations-nearest#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/locations-nearest.json)


## gumtree/product

`GET /v1/gumtree/product`

One listing's page: description, price, category path, location, attributes, images, the seller's profile and the seller ids the seller routes take.

*Gumtree listing*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Ad id (or pass url, the listing's page) — e.g. `1513645531` |
| `url` | no | The listing's page URL instead of an id |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/product?id=1513645531" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "age_days": 0,
  "attributes": [
    {
      "label": "example",
      "value": "example"
    }
  ],
  "category": "example",
  "category_id": "example",
  "category_path": [
    "example"
  ],
  "contact": {
    "has_email": false,
    "has_phone": false,
    "has_website": false
  },
  "currency": "example",
  "description": "example",
  "id": "example",
  "images": [
    "example"
  ],
  "images_count": 0,
  "location": {
    "approximate": false,
    "id": "example",
    "latitude": 0,
    "longitude": 0,
    "name": "example"
  },
  "map_image_url": "https://example.com/example",
  "platform": "example",
  "posted": "example",
  "price": 0,
  "price_label": "example",
  "price_pence": 0,
  "seller": {
    "active_status": "example",
    "identity_verified": false,
    "platform": "example",
    "rating": {
      "max": 0,
      "value": 0,
      "votes": 0
    },
    "type": "example",
    "user_id": "example"
  },
  "title": "example",
  "trade_seller": false,
  "type": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/product#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/product.json)


## gumtree/product-similar

`GET /v1/gumtree/product-similar`

Listings similar to one listing.

*Gumtree similar listings*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Ad id — e.g. `1513645531` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/product-similar?id=1513645531" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "currency": "example",
      "delivery": false,
      "featured": false,
      "has_video": false,
      "id": "example",
      "id_verified": false,
      "image_url": "https://example.com/example",
      "platform": "example",
      "position": 0,
      "price": 0,
      "price_label": "example",
      "price_pence": 0,
      "shipping": false,
      "thumbnail_url": "https://example.com/example",
      "title": "example",
      "type": "example",
      "urgent": false,
      "url": "https://example.com/example"
    }
  ],
  "listing_id": "example",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/product-similar#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/product-similar.json)


## gumtree/search

`GET /v1/gumtree/search`

One page of Gumtree UK listings for a keyword: title, price, location, age, seller flags and URL.

*Gumtree search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keyword — e.g. `laptop` |
| `category` | no | Category slug — e.g. `laptops` |
| `location` | no | Location slug — e.g. `london` |
| `page` | no | Page number — e.g. `1` |
| `cursor` | no | Continue with the complete cursor from the previous response and the original query. Omit page, or use the same page encoded by the cursor. A continuation stays on its original source. Bare numbered pages use the primary source. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/search?query=laptop" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "category": "example",
  "count": 0,
  "cursor": null,
  "has_more": false,
  "items": [
    {
      "age_days": 0,
      "category_id": "example",
      "currency": "example",
      "delivery": false,
      "featured": false,
      "has_video": false,
      "id": "example",
      "id_verified": false,
      "images": 0,
      "location": "example",
      "platform": "example",
      "position": 0,
      "price": 0,
      "price_pence": 0,
      "title": "example",
      "trade_seller": false,
      "type": "example",
      "url": "https://example.com/example"
    }
  ],
  "location": "example",
  "page": 0,
  "query": "example",
  "scraped_at": "2026-09-01T12:00:00Z",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/search.json)


## gumtree/search-suggestions

`GET /v1/gumtree/search-suggestions`

Keyword suggestions for a partial search, each with the category it belongs to.

*Gumtree search suggestions*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Partial keyword — e.g. `iph` |
| `category` | no | Category id to scope the suggestions |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/search-suggestions?query=iph" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "category": "example",
      "category_id": "example",
      "term": "example"
    }
  ],
  "query": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/search-suggestions#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/search-suggestions.json)


## gumtree/trending

`GET /v1/gumtree/trending`

The search terms trending on the site right now.

*Gumtree trending searches*

| Parameter | Required | Description |
| --- | --- | --- |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/gumtree/trending" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "position": 0,
      "term": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/gumtree/trending#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/gumtree/trending.json)