# Gumtree Search API Documentation

Search Gumtree UK classifieds in any category, including cars and property. Each result has the ad id, title, url, location, price (amount, currency and period for rentals) and the display price text, a short description, the featured and urgent flags, category, seller type (private or trade), image count, one image and its position. Filter by category, price range, location and distance and sort by date, price or relevance. Price sorts list featured ads first, then sort the rest. Page with the page parameter: has_more is true while more pages exist and next_page is the next page number. A valid empty search is a successful response.

- **Documentation:** [https://scrappa.co/docs/gumtree-api/gumtree_search](https://scrappa.co/docs/gumtree-api/gumtree_search)
- **API group:** Gumtree API
- **Endpoint:** `GET https://scrappa.co/api/gumtree/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search keywords, e.g. bike. Provide query or category_id. |
| `category_id` | string | No | Numeric Gumtree category id from the categories endpoint, e.g. 86 for other bikes, 151 for sofas, 2551 for cars, vans and motorbikes, 10201 for flats and houses. Provide query or category_id. |
| `page` | integer | No | 1-based page number, 1 to 1000. Defaults to 1. |
| `size` | integer | No | Results per page, 1 to 20. Defaults to 20. |
| `min_price` | integer | No | Minimum price in GBP. |
| `max_price` | integer | No | Maximum price in GBP. Must be at least min_price. |
| `location_id` | string | No | Numeric location id from the location endpoint, e.g. 895643. Use together with location_type. |
| `location_type` | string | No | LOCATION or POSTCODE. Required with location_id. |
| `distance` | string | No | Radius around the location: NATIONWIDE, ZERO, ONE, THREE, FIVE, TEN, FIFTEEN, THIRTY, FIFTY, SEVENTY_FIVE, HUNDRED, HUNDRED_FIFTY, TWO_HUNDRED_FIFTY or FIVE_HUNDRED miles. Defaults to NATIONWIDE. |
| `sort` | string | No | DATE_DESCENDING, PRICE_ASCENDING, PRICE_DESCENDING or RELEVANCE_DESCENDING. Defaults to DATE_DESCENDING. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/gumtree/search?query=bike&category_id=86"
```

## Example response

```json
{
    "success": true,
    "data": {
        "results": [
            {
                "id": "1803847692",
                "title": "Mountain Bike",
                "url": "https://www.gumtree.com/p/x/x/1803847692",
                "location": "Newcastle",
                "price": {
                    "amount": 65,
                    "currency": "GBP"
                },
                "price_text": "\u00a365",
                "description": "Carrera mountain bike for sale. 18\" frame. Brand new tyres. Everything works as it should. Pickup from Killingworth. Only calls can be answered thanks for looking - Jim",
                "is_featured": true,
                "category_id": "86",
                "category": "Other Bikes",
                "seller_type": "Private",
                "image_count": 6,
                "images": [
                    "https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/63295a6c2215494190_c531d747ddb1/257"
                ],
                "position": 1
            },
            {
                "id": "1803754465",
                "title": "Ladies bike for sale , excellent condition",
                "url": "https://www.gumtree.com/p/x/x/1803754465",
                "location": "Byfleet",
                "price": {
                    "amount": 150,
                    "currency": "GBP"
                },
                "price_text": "\u00a3150",
                "description": "Used twice and helmet , mitts included. Frame has bosses for panniers.",
                "is_featured": true,
                "category_id": "86",
                "category": "Other Bikes",
                "seller_type": "Private",
                "image_count": 8,
                "images": [
                    "https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/6c60cff41cd64f86bc_dda2a0f6c8fd/257"
                ],
                "position": 2
            }
        ],
        "total": 7737,
        "page": 1,
        "size": 20,
        "has_more": true,
        "next_page": 2
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable. |
| 502 | Invalid Source Response | The upstream answered with a shape that no longer matches the documented contract. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)