# Gumtree Listings Scraper (`neuro-scraper/gumtree-listings-scraper`) Actor

Gumtree Scraper SD - Gumtree Scraper is a classifieds data tool that extracts Gumtree UK search results and ad pages: title, price, location, postcode, seller type, posting time, images, attributes such as make, model and mileage, featured flag. No login.

- **URL**: https://apify.com/neuro-scraper/gumtree-listings-scraper.md
- **Developed by:** [Neuro Scraper](https://apify.com/neuro-scraper) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Gumtree Scraper

Gumtree Scraper collects ads from **Gumtree UK (gumtree.com)**: search results for any keyword, category,
town or postcode, page after page, plus single ad pages. Each ad comes with its price as a number, location,
postcode, seller type, posting time, images and the ad's attributes (condition and brand, or make, model,
year, mileage and fuel for cars). Optionally it opens every ad page for the full description and seller details.
No login, public data only.

#### Input

| Field | Type | Default | What it does |
|---|---|---|---|
| `searchTerms` | list | `["bike"]` (prefill) | Keywords as typed in the Gumtree search box, one per line. |
| `location` | text | `uk` | `uk`, a town / area (`manchester`, `london`) or a postcode (`M1 1AE`). |
| `category` | text | `all` | Gumtree category slug: `cars`, `bicycles`, `for-sale`, `flats-houses`, `jobs`, `pets` ... With no search term, a category or location other than `all` / `uk` lists the newest ads there. |
| `startUrls` | list | – | gumtree.com search / category result URLs (filters kept) and ad URLs (`/p/<category>/<title>/<adId>`), detected automatically. |
| `maxItems` | integer | 20 | Total ads to return. |
| `maxPagesPerSearch` | integer | 50 | Page limit per search (Gumtree serves at most 50). |
| `sort` | select | Gumtree's default | `relevance`, `date`, `price_lowest_first`, `price_highest_first`, `distance`. |
| `distance` | select | – | Gumtree's "+ N miles" around the location (1 … 100, 1000 = nationwide). |
| `minPrice` / `maxPrice` | integer | – | Price range in £; applied by Gumtree only with a specific category. |
| `includeDetails` | boolean | false | Open each ad page: full description, all attributes, category path, seller name, rating, years on Gumtree, ad count, last active, creation time. 1 extra request per ad. |
| `proxyConfiguration` | proxy | RESIDENTIAL, GB | Proxy used for every request. |

#### Output

| Field | Description |
|---|---|
| `id`, `url`, `title` | Gumtree ad id, ad URL, title |
| `price`, `currency`, `priceText` | Price as a number (`11299.0`), `GBP`, and as shown (`£11,299.00`) |
| `location`, `postcode`, `latitude`, `longitude` | Area as shown, the ad's postcode, coordinates when the seller shows the map |
| `category`, `categoryId` | Leaf category (for cars: the make) |
| `sellerType`, `sellerId` | Private / Trade / Business, Gumtree's seller id |
| `isFeatured`, `isUrgent` | Paid "Featured" / "Urgent" badges (search rows) |
| `postedAt`, `postedAgo` | Posting time (ISO, UTC) and as shown (`2 hours ago`) |
| `description` | First ~250 characters in search rows; the full text with `includeDetails` or for ad URLs |
| `attributes` | Object of the ad's attributes, e.g. `{"Make": "Volkswagen", "Mileage": "26146 miles"}` |
| `imageUrl`, `images`, `imageCount` | Main image, all image URLs, number of images |
| `distanceMiles` | Distance from the searched location (search rows) |
| `favouriteCount` | How many users saved the ad |
| `page`, `position`, `searchUrl` | Result page, position on it, results page URL (search rows) |
| `searchTerm` / `inputUrl` | The input that produced the row |
| `categoryPath`, `sellerName`, `sellerRating`, `sellerReviewsCount`, `sellerPostingFor`, `sellerAdsCount`, `sellerLastActive`, `createdAt` | With `includeDetails` and for ad URLs |
| `scrapedAt` | Time of scraping (ISO, UTC) |

#### Measured limits

Measured 2026-10-03 from one residential IP without a proxy (details in TEST_REPORT.md).

- A results page holds 26-34 ads; Gumtree serves at most 50 pages per search or category URL (page 51
  redirects). Measured speed: 20 ads in 2-3 s (1 page), 100 ads in 7 s (4 pages), 600 ads in 29 s (22 pages).
- Featured ads (up to 5 per page) stay on top whatever the sort and repeat on every page; repeats are dropped.
- Bot check: after 3-9 keyword-search pages within a few minutes Gumtree answers that IP with a JavaScript
  check for about 10 minutes; 22 category pages in a row passed without it. The Actor never answers the
  check: with the default proxy it continues on a new UK residential IP (up to 3 per request); without a proxy
  it stops after 2 refused requests and keeps the rows collected.
- A sort or price range on a keyword search in category `all` makes Gumtree search only the category it
  guesses (sofa: 305 instead of 1,865 ads). A price range is applied only with a specific category. An
  unknown place (e.g. `Manchester, UK`) makes Gumtree search the whole UK. Each case is logged as a WARNING.
- A postcode searches 10 miles around by default.
- `includeDetails` costs 1 request per ad (0.5-0.6 MB). Seller rating, ad count and last-active time are
  published for private sellers only (empty for the 4 trade dealers tested).
- Not collected: phone numbers and contact details (masked, login required) and number plates.

#### Example input

```json
{
  "searchTerms": ["bmw"],
  "category": "cars",
  "location": "manchester",
  "distance": "10",
  "maxItems": 100,
  "includeDetails": false
}
```

# Actor input Schema

## `searchTerms` (type: `array`):

What you would type in the Gumtree search box, one per line. Example: bike

## `location` (type: `string`):

Where to search: uk (whole country), a town or area such as manchester or london, or a postcode such as M1 1AE.

## `category` (type: `string`):

Gumtree category slug: all, cars, motorbikes-scooters, vans, for-sale, bicycles, flats-houses, jobs, pets, business-services, community ... (the last part of a category page's address, e.g. bicycles in gumtree.com/for-sale/sports-leisure-travel/bicycles). Price limits only apply with a specific category. With no search term, a category or location other than all / uk lists the newest ads there.

## `startUrls` (type: `array`):

gumtree.com search or category result URLs copied from the browser (their filters are kept), e.g. https://www.gumtree.com/search?search_category=cars\&search_location=manchester, and/or ad URLs such as https://www.gumtree.com/p/<category>/<title>/<adId>. Detected automatically. gumtree.com.au (Australia) is a different site and is not supported.

## `maxItems` (type: `integer`):

Maximum number of ads to return in total. Result pages are read one after another until this number is reached or Gumtree has no next page.

## `maxPagesPerSearch` (type: `integer`):

Safety limit on result pages read per search term or URL. Gumtree itself serves at most 50 pages (about 30 ads each) per search.

## `sort` (type: `string`):

Order of the results for search terms. Empty = Gumtree's default (most relevant for a keyword, newest when browsing a category). Featured ads always stay on top of each page.

## `distance` (type: `string`):

Widen the search to this many miles around the location (Gumtree's "+ N miles" filter). Empty = the location's own area.

## `minPrice` (type: `integer`):

Only ads priced at or above this. Gumtree applies it when a specific category is set (e.g. bicycles); with category all it ignored it in our tests - the log says so when that happens.

## `maxPrice` (type: `integer`):

Only ads priced at or below this. Same rule as the minimum price.

## `includeDetails` (type: `boolean`):

Adds the full description, all attributes, category path, seller name, rating, years on Gumtree, ad count and last-active time, and the ad creation time. Costs 1 extra request per result, so runs take longer. Seller phone numbers need a Gumtree login and are never collected.

## `proxyConfiguration` (type: `object`):

Gumtree shows a JavaScript bot check to an IP address after a few quick keyword searches (3-9 search pages within minutes in our tests; category pages were far less affected). UK residential proxy is the default: each time the check appears the Actor continues on a new IP.

## Actor input object example

```json
{
  "searchTerms": [
    "bike"
  ],
  "location": "uk",
  "category": "all",
  "startUrls": [],
  "maxItems": 20,
  "maxPagesPerSearch": 50,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "GB"
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "bike"
    ],
    "location": "uk",
    "category": "all",
    "startUrls": [],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "GB"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("neuro-scraper/gumtree-listings-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["bike"],
    "location": "uk",
    "category": "all",
    "startUrls": [],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "GB",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("neuro-scraper/gumtree-listings-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "bike"
  ],
  "location": "uk",
  "category": "all",
  "startUrls": [],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "GB"
  }
}' |
apify call neuro-scraper/gumtree-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,neuro-scraper/gumtree-listings-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4qoyHUou9U8ViRyFA/builds/OtaxMgTOhLv8ihNkj/openapi.json