# Gumtree Scraper (`shahidirfan/gumtree-scraper`) Actor

Extract Gumtree listings data for market intelligence, competitive pricing analysis, and lead generation. Scrape classifieds, properties, and products at scale with structured output.

- **URL**: https://apify.com/shahidirfan/gumtree-scraper.md
- **Developed by:** [Shahid Irfan](https://apify.com/shahidirfan) (community)
- **Categories:** Lead generation, Real estate, Automation
- **Stats:** 22 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Gumtree Scraper

Extract Gumtree listings at scale from search results across jobs, property, motors, and general classifieds. Collect titles, prices, locations, seller labels, category-specific facts, descriptions, and media links in a fast, reliable workflow built for monitoring, research, and lead generation.

***

### Features

- **Search URL support** — Start from any Gumtree results URL and preserve its filters.
- **Keyword and location search** — Build new Gumtree searches from keyword, category, and location inputs.
- **Category coverage** — Works across jobs, property, motors, and other Gumtree listing types from the URL you provide.
- **Fast enrichment** — Collect fuller descriptions and category-specific fields in parallel for higher throughput.
- **Pagination handling** — Continue across Gumtree result pages until your target volume is reached.
- **Clean datasets** — Empty values are removed before data is written, so the dataset stays compact and useful.

***

### Use Cases

#### Market Monitoring

Track changing prices, listing volume, and seller types for categories you care about. This is useful for second-hand resale research, local market checks, and competitor monitoring.

#### Lead Collection

Build datasets of listings that match specific locations, categories, or keywords. Teams can use this for outreach, sourcing, and classified aggregation workflows.

#### Price Analysis

Collect price snapshots together with condition, category, and location fields. This makes it easier to compare supply across regions or category slices.

#### Listing Research

Capture descriptions, listing metadata, and category-specific facts for analysis. This is helpful for content studies, merchandising reviews, and trend discovery.

#### Classified Aggregation

Normalize Gumtree listings from different verticals into one dataset while preserving category-specific details. This is useful when the same workflow needs jobs, property, and general resale inventory together.

***

### Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `startUrl` | String | No | `https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom` | Start from a specific Gumtree search URL. |
| `keyword` | String | No | `""` | Optional keyword for Gumtree search. |
| `location` | String | No | `United Kingdom` | Gumtree location filter. |
| `category` | String | No | `all` | Gumtree category slug such as `all`, `jobs`, or `for-sale`. |
| `sort` | String | No | `date` | Sort order: `date`, `price_lowest_first`, `price_highest_first`, or `distance`. |
| `searchInDescription` | Boolean | No | `false` | Search title and description instead of title only. |
| `collectDetails` | Boolean | No | `true` | Fetch listing pages to collect richer descriptions and category-specific fields. |
| `results_wanted` | Integer | No | `20` | Maximum number of listings to collect. |
| `max_pages` | Integer | No | `10` | Safety cap for paginated result pages. |
| `proxyConfiguration` | Object | No | Residential Apify Proxy | Proxy settings for more reliable collection. |

***

### Output Data

Each dataset item can contain:

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Gumtree listing ID. |
| `url` | String | Absolute Gumtree listing URL. |
| `title` | String | Listing title. |
| `price` | String | Displayed listing price. |
| `location` | String | Location shown on Gumtree. |
| `category` | String | Listing category name. |
| `categoryId` | String | Gumtree category ID. |
| `listingCategoryId` | String | Listing category tracking ID from Gumtree. |
| `listingVertical` | String | Normalized vertical such as `jobs`, `property`, `motors`, or `classifieds`. |
| `postedDate` | String | Relative posted date from the results page. |
| `postedAt` | String | Detail-page posted timestamp text when collected. |
| `shortDescription` | String | Search result preview text. |
| `description` | String | Detail-page description text when collected. |
| `imageUrl` | String | Primary image URL. |
| `imageUrls` | Array | All available image URLs collected for the listing. |
| `numberOfImages` | Integer | Reported image count. |
| `condition` | String | Condition value when available. |
| `sellerType` | String | Seller label such as private or trade. |
| `sellerId` | String | Gumtree seller ID when available. |
| `accountId` | String | Gumtree account ID when available. |
| `sellerName` | String | Seller name if exposed on the listing page. |
| `sellerPostingHistory` | String | Seller posting duration text when collected. |
| `sellerActiveStatus` | String | Seller activity text when collected. |
| `applyUrl` | String | External apply link for job listings when available. |
| `revealPhoneUrl` | String | Gumtree phone reveal URL when available. |
| `status` | String | Listing status reported by Gumtree. |
| `adItemType` | String | Item type classification from Gumtree. |
| `featured` | Boolean | Whether the listing is featured. |
| `urgent` | Boolean | Whether the listing is marked urgent. |
| `premium` | Boolean | Whether the listing is premium. |
| `bumpup` | Boolean | Whether the listing is bumped up. |
| `standout` | Boolean | Whether the listing is marked standout. |
| `hasVideo` | Boolean | Whether the listing has video content. |
| `proAccount` | Boolean | Whether the seller is a pro account. |
| `attributes` | Array | Structured Gumtree attribute objects for the listing. |
| `attributeMap` | Object | Flattened attribute map merged from list and detail data. |
| `detailAttributes` | Object | Extra label/value pairs collected from the listing page. |
| `categorySpecific` | Object | Nested category-aware fields for jobs, property, motors, and shared values. |

***

### Usage Examples

#### Default United Kingdom Search

```json
{
	"startUrl": "https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom",
	"collectDetails": true,
	"results_wanted": 20,
	"max_pages": 2
}
```

#### Keyword and Category Search

```json
{
	"keyword": "sofa",
	"location": "London",
	"category": "for-sale",
	"sort": "date",
	"results_wanted": 50,
	"collectDetails": false
}
```

#### Search Title and Description

```json
{
	"startUrl": "https://www.gumtree.com/jobs",
	"collectDetails": true,
	"results_wanted": 40,
	"max_pages": 4
}
```

***

### Sample Output

```json
{
	"id": "1510979577",
	"url": "https://www.gumtree.com/p/road-bikes/frog-bike-model-52-with-20-wheels/1510979577",
	"title": "Frog bike model 52 with 20\" wheels",
	"price": "£140.00",
	"location": "Stirling",
	"category": "Road Bikes",
	"listingVertical": "classifieds",
	"postedDate": "Just now",
	"shortDescription": "Good condition overall with only a few light scratches. It’s second-hand but everything works as it should.",
	"description": "Good condition overall with only a few light scratches. It’s second-hand but everything works as it should.",
	"imageUrl": "https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/a878a32cdd6b46089a_dcf801a7036f/86",
	"imageUrls": [
		"https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/a878a32cdd6b46089a_dcf801a7036f/86",
		"https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/89e22b3c902d4cfea6_7811a2894484/86"
	],
	"numberOfImages": 3,
	"condition": "Good condition",
	"sellerType": "Private",
	"status": "LIVE",
	"adItemType": "http://schema.org/Product",
	"attributeMap": {
		"commonForSaleCondition": "Good condition",
		"sellerType": "Private"
	},
	"sellerId": "68147461",
	"accountId": "67600593",
	"categorySpecific": {
		"common": {
			"condition": "Good condition",
			"sellerType": "Private"
		}
	},
	"attributes": [
		{
			"name": "Condition",
			"value": "Good condition",
			"key": "common_for_sale_condition"
		},
		{
			"name": "Seller type",
			"value": "Private",
			"key": "seller_type"
		}
	]
}
```

***

### Tips for Best Results

#### Prefer Search URLs For Repeatable Runs

- Use a saved Gumtree search URL when you want the exact same filters every time.
- This is the easiest way to keep category and location settings consistent.

#### Keep QA And Smoke Tests Small

- Start with one or two result pages to validate output quickly.
- Increase volume only after you confirm the dataset shape you need.

#### Use Residential Proxies For Reliability

- Residential proxies are recommended for larger runs.
- This is especially useful when collecting detail pages at higher volume.

#### Tune Parallel Detail Collection

- The actor uses internal request concurrency and timeout defaults tuned for stable production runs.
- If you need different operational limits, adjust the code-level defaults before redeploying.

***

### Integrations

- **Google Sheets** — Export listing datasets for quick filtering and reporting.
- **Airtable** — Store Gumtree listings in a searchable workspace.
- **Make** — Trigger follow-up automations when new listings appear.
- **Zapier** — Send listing data into CRMs, alerts, or spreadsheets.
- **Webhooks** — Deliver structured output directly into your own systems.

#### Export Formats

- **JSON** — For APIs, scripts, and custom processing.
- **CSV** — For spreadsheet workflows.
- **Excel** — For reporting and manual review.
- **XML** — For older integrations and import pipelines.

***

### Frequently Asked Questions

#### Can I scrape any Gumtree search URL?

Yes. If you provide a Gumtree search URL, the actor starts from that page and keeps the URL filters intact.

#### Does the actor collect extra detail fields?

Only when `collectDetails` is enabled. If you disable it, the actor saves the search-page data only.

#### Does it work for jobs and property?

Yes. The actor supports jobs, property, motors, and other Gumtree listing types, and keeps category-specific fields when they are available.

#### Why are some fields missing on certain items?

Gumtree does not expose the same fields for every listing. Empty values are removed instead of being stored as `null`.

#### How many listings can I collect?

You can collect as many listings as Gumtree makes available, subject to your `max_pages` setting and the actor's internal runtime limits.

#### Is proxy configuration necessary?

Small runs may work without proxies, but residential proxies are recommended for the most stable production runs.

***

### Support

For issues or feature requests, use the Apify Console issue and support channels connected to this actor.

#### Resources

- [Apify Documentation](https://docs.apify.com/)
- [Apify API Reference](https://docs.apify.com/api/v2)
- [Apify Schedules](https://docs.apify.com/platform/schedules)

***

### Legal Notice

This actor is intended for legitimate data collection and monitoring workflows. Users are responsible for complying with Gumtree terms, local regulations, and applicable data-use requirements.

# Actor input Schema

## `startUrl` (type: `string`):

Start from a specific Gumtree search URL. When provided, this takes priority over the keyword, location, and category inputs.

## `keyword` (type: `string`):

Optional search term for Gumtree listings.

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

Gumtree location filter such as United Kingdom, London, or Scotland.

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

Gumtree category slug, for example all, jobs, for-sale, or flats-houses.

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

Sort results by Gumtree sort key. Common values are date, price\_lowest\_first, price\_highest\_first, and distance.

## `searchInDescription` (type: `boolean`):

When enabled, Gumtree searches the title and description fields.

## `collectDetails` (type: `boolean`):

When enabled, the actor fetches listing detail pages over HTTP to collect richer descriptions and category-specific fields.

## `results_wanted` (type: `integer`):

The maximum number of listings to collect.

## `max_pages` (type: `integer`):

Safety limit for paginated search pages.

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

Residential proxies are recommended for the most reliable Gumtree runs.

## Actor input object example

```json
{
  "startUrl": "https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom",
  "location": "United Kingdom",
  "category": "all",
  "sort": "date",
  "searchInDescription": false,
  "collectDetails": true,
  "results_wanted": 20,
  "max_pages": 2,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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 = {
    "startUrl": "https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom",
    "keyword": "",
    "location": "United Kingdom",
    "category": "all",
    "sort": "date",
    "results_wanted": 20,
    "max_pages": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("shahidirfan/gumtree-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 = {
    "startUrl": "https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom",
    "keyword": "",
    "location": "United Kingdom",
    "category": "all",
    "sort": "date",
    "results_wanted": 20,
    "max_pages": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("shahidirfan/gumtree-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 '{
  "startUrl": "https://www.gumtree.com/search?search_category=all&search_location=United%20Kingdom",
  "keyword": "",
  "location": "United Kingdom",
  "category": "all",
  "sort": "date",
  "results_wanted": 20,
  "max_pages": 2
}' |
apify call shahidirfan/gumtree-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shahidirfan/gumtree-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/gmdlQ2qMClBDOgvPc/builds/DCyyAQ3oD43Y6O9X2/openapi.json