### π€ For AI Agents & LLM Apps
Compact reference for AI agents calling this actor via the [Apify MCP server](https://mcp.apify.com) or the Apify API (actor: `memo23/gumtree-cheerio`).
**Purpose:** Scrapes Gumtree listings across the UK, Australia, New Zealand, and South Africa sites from either exact URLs or filter fields, returning structured ad data (56+ fields on detail pages).
**Minimal input:**
```json
{
"startUrls": [{ "url": "https://www.gumtree.com.au/s-cars-vans-utes/perth/c18320l3008303" }],
"maxItems": 20
}
```
Search-mode variant (no URLs): `{ "gumtreeSearchRegion": "UK", "gumtreeSearchKeyword": "computer", "gumtreeSearchLocation": "Edinburgh", "maxItems": 20 }`
**Output:** one row per listing β adId, shortId, title, price {amount, formattedAmount, currency, priceType}, description, link, imageUrl, photoCount, pictures, location, creationDate, sellerName, category, bedrooms, bathrooms, dwellingType, userName, attributePhone, geo {latitude, longitude, fullAddress}, postedDate, sellerId, sellerPhone, status.
**Behaviors an agent should know:**
- Two input modes: `startUrls` OR `Search by filters` (`gumtreeSearchRegion` + fields). If both are set, `startUrls` take precedence.
- Filter mode: AU/NZ require `gumtreeSearchCategoryId` + `gumtreeSearchLocationId`; UK uses keyword/location; ZA uses category slug + location slug.
- Always set `maxItems` (default 10000 per start URL) to cap cost.
- `includeListingDetails` (default true) fetches each ad's detail page; `includePhoneDetails` (default false) adds seller phone for AU/UK (premium); `enrichEmails` (default false, experimental) adds contactEmail/contactWebsite.
- `monitoringMode: true` scrapes only listings new since the previous run; `listingStartDate` (YYYY-MM-DD) limits to listings newer than a date.
- Billing: Pay-per-event billing β see the Pricing tab on the actor page.
### β οΈ Disclaimer
This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Gumtree.com Limited, its regional operating entities, or any of their subsidiaries. All trademarks mentioned are the property of their respective owners.
The scraper accesses only publicly available classified-listing pages on gumtree.com, gumtree.com.au, and gumtree.co.za β no authenticated endpoints, paid features, or content behind the Gumtree login wall. Users are responsible for ensuring their use complies with Gumtree's Terms of Service, applicable data-protection law (GDPR, CCPA, etc.), and any contractual obligations of their own organization.
### SEO Keywords
gumtree scraper, scrape gumtree, gumtree.com scraper, gumtree.com.au scraper, gumtree API, Apify gumtree, classifieds scraper, classified listings scraper, used car listings scraper, real estate listings scraper, property data scraper, seller contact data, classifieds price monitoring, marketplace data extraction, lead generation data, UK classifieds data, Australia classifieds data, second-hand goods data, online marketplace intelligence
# Actor input Schema
## `startUrls` (type: `array`):
Power-user mode: exact URLs. Leave empty (or omit) if you use **Search by filters** instead. **If you fill both this and filters, only these URLs are used.**
## `includeListingDetails` (type: `boolean`):
Whether to include listing details in the output.
## `includePhoneDetails` (type: `boolean`):
Whether to include phone details in the output.
## `enrichEmails` (type: `boolean`):
If enabled, finds a contact email for each result from its own website (or by discovering it from the name). Adds contactEmail + contactWebsite columns plus a detailed emailEnrichment object. Best-effort.
## `monitoringMode` (type: `boolean`):
If checked, it will only scrape newly listings compared to what has been scraped in previous runs.
## `listingStartDate` (type: `string`):
Format should be YYYY-MM-DD, e.g., 2025-02-20
## `gumtreeSearchRegion` (type: `string`):
Which Gumtree site to search. Leave empty if you only use **Start URLs**.
## `gumtreeSearchKeyword` (type: `string`):
Optional search text.
## `gumtreeSearchLocation` (type: `string`):
UK: free-text (e.g. Edinburgh). AU/NZ/ZA: optional; AU/NZ still need Category ID + Location ID.
## `gumtreeSearchCategorySlug` (type: `string`):
UK: search\_category (e.g. all, property-to-rent). ZA: segment without `s-` (e.g. houses-flats-for-sale).
## `gumtreeSearchLocationSlug` (type: `string`):
ZA: middle path segment (e.g. pretoria-tshwane).
## `gumtreeSearchSort` (type: `string`):
Mapped per site (AU/NZ: sort=date|rank in query where supported).
## `gumtreeSearchCategoryId` (type: `string`):
Required for Australia & New Zealand filter mode (with Location ID). Copy the number after c in the path segment that looks like c18320l3008303.
Examples: AU cars search β¦/s-cars-vans-utes/perth/c18320l3008303 β category 18320. ZA β¦/v1c9074l3100094p1 β category 9074.
Not used for UK (UK uses category slug + free-text location instead).
## `gumtreeSearchLocationId` (type: `string`):
Required for Australia & New Zealand filter mode (with Category ID). Copy the number after l in the same segment (before any ?).
Examples: β¦/c18320l3008303 β location 3008303. ZA β¦v1c9074l3100094p1 β location 3100094.
Open any real search on gumtree.com.au / gumtree.co.nz / gumtree.co.za and paste the IDs from the address bar.
## `maxItems` (type: `integer`):
Maximum listings to collect for each search start URL. If you add several search URLs, each can yield up to this many items (subject to pay-per-result and charge limits).
## `maxConcurrency` (type: `integer`):
Maximum number of pages that can be processed at the same time.
## `minConcurrency` (type: `integer`):
Minimum number of pages that will be processed at the same time.
## `maxRequestRetries` (type: `integer`):
Number of times the crawler will retry a failed request before giving up.
## `proxy` (type: `object`):
Specifies proxy servers that will be used by the scraper in order to hide its origin.
For details, see Proxy configuration in README.
## Actor input object example
```json
{
"startUrls": [
{
"url": "https://www.gumtree.com.au/s-cars-vans-utes/perth/caryear-2017__/c18320l3008303?forsaleby=ownr&view=gallery"
}
],
"includeListingDetails": true,
"includePhoneDetails": false,
"enrichEmails": false,
"monitoringMode": false,
"gumtreeSearchSort": "most_recent",
"maxItems": 10000,
"maxConcurrency": 30,
"minConcurrency": 1,
"maxRequestRetries": 30,
"proxy": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
```
# Actor output Schema
## `results` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"startUrls": [
{
"url": "https://www.gumtree.com.au/s-cars-vans-utes/perth/caryear-2017__/c18320l3008303?forsaleby=ownr&view=gallery"
}
],
"proxy": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("memo23/gumtree-cheerio").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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"startUrls": [{ "url": "https://www.gumtree.com.au/s-cars-vans-utes/perth/caryear-2017__/c18320l3008303?forsaleby=ownr&view=gallery" }],
"proxy": {
"useApifyProxy": True,
"apifyProxyGroups": ["RESIDENTIAL"],
},
}
# Run the Actor and wait for it to finish
run = client.actor("memo23/gumtree-cheerio").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 '{
"startUrls": [
{
"url": "https://www.gumtree.com.au/s-cars-vans-utes/perth/caryear-2017__/c18320l3008303?forsaleby=ownr&view=gallery"
}
],
"proxy": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}' |
apify call memo23/gumtree-cheerio --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,memo23/gumtree-cheerio"
}
}
}
```
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 ` 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/Hopq3yebWETdVJ4wA/builds/ET2ffHx925L0BxrFA/openapi.json