# Gumtree Data Extractor (`kawsar/gumtree-data-extractor`) Actor Gumtree scraper that pulls listing titles, prices, locations, and URLs from search results, so you can track the UK classifieds market without doing it by hand. - **URL**: https://apify.com/kawsar/gumtree-data-extractor.md - **Developed by:** [Kawsar](https://apify.com/kawsar) (community) - **Categories:** Automation, Developer tools, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $6.99 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Data Extractor Gumtree Data Extractor scrapes Gumtree search results and returns the listing data as a structured dataset. Give it one or more keywords, optional locations, and optional categories, and it pulls titles, prices, seller locations, post age, delivery flags, trade seller status, featured placement, and a direct URL for every result across as many pages as you need. You can run a single search or batch dozens of keyword/location/category combinations in one go. Each combination is scraped independently up to a configurable item limit, so you always know exactly which search produced each row. Output goes straight to the Apify dataset. Download as JSON, CSV, or Excel, or connect it to Google Sheets, a database, or any BI tool via the Apify API. --- ### How multiple inputs work The actor accepts single values or lists for search queries, locations, and categories. It builds every combination and scrapes each one separately. **Example:** 3 queries x 2 locations x 1 category = 6 separate searches, each returning up to your configured max items. ```` searchQueries: \["laptop", "macbook", "gaming pc"] locations: \["london", "manchester"] categories: \["laptops"] → laptop + london + laptops → laptop + manchester + laptops → macbook + london + laptops → macbook + manchester + laptops → gaming pc + london + laptops → gaming pc + manchester + laptops ```` Every result row includes `searchKeyword`, `searchLocation`, and `searchCategory` fields so you can filter by combination in your spreadsheet or database. --- ### What it collects | Field | Type | Description | |---|---|---| | listingId | integer | Unique Gumtree listing ID | | listingTitle | string | Listing title as shown on Gumtree | | price | integer | Price in GBP (0 = free) | | pricePennies | integer | Price in pence for precision | | location | string | Seller location, e.g. "Salford, Manchester" | | ageDays | integer | Days since the listing was posted | | isTrade | boolean | True if the seller is a business/trade account | | isFeatured | boolean | True if the listing has paid featured placement | | isDelivery | boolean | True if the seller offers delivery | | isGBGVerified | boolean | True if the seller passed GBG identity verification | | categoryId | integer | Numeric Gumtree category ID | | numberOfImages | integer | Number of photos attached to the listing | | hasVideo | boolean | True if the listing includes a video | | position | integer | Zero-based position in the search results | | recallSource | string | How Gumtree ranked the result (absent for featured listings) | | listingUrl | string | Full URL to the listing page | | searchKeyword | string | Keyword used for this search | | searchLocation | string | Location slug used (empty = all UK) | | searchCategory | string | Category slug used (empty = all categories) | | totalResults | integer | Total results Gumtree reports for this search | | pageNumber | integer | Page number this listing was collected from | | scrapedAt | string | ISO 8601 UTC timestamp | --- ### Input | Field | Type | Required | Default | Description | |---|---|---|---|---| | searchQueries | string list | yes | | One or more keywords. Each runs as a separate search. | | locations | string list | no | | Location slugs to filter by (e.g. london, manchester). Leave empty for all UK. | | categories | string list | no | | Category slugs to narrow results (e.g. laptops, cars). Leave empty for all categories. | | maxItemsPerQuery | integer | no | 50 | Max listings per query/location/category combination. The actor pages automatically until this limit is reached. Max 500. | | requestTimeoutSecs | integer | no | 30 | Per-request timeout in seconds. | At least one of `searchQuery` or `searchQueries` is required. --- ### Example input — single search ```json { "searchQueries": ["gaming chair"], "locations": ["london"], "categories": ["furniture-storage"], "maxItemsPerQuery": 90 } ```` ### Example input — batch search ```json { "searchQueries": ["laptop", "macbook pro", "gaming pc"], "locations": ["london", "manchester", "birmingham"], "categories": ["laptops"], "maxItemsPerQuery": 50 } ``` This produces 9 combinations (3 queries x 3 locations x 1 category), up to 50 items each, for a maximum of 450 rows. The actor pages automatically through Gumtree results until each limit is filled. *** ### Example output ```json { "listingId": 1513777639, "listingTitle": "Adjustable gaming chair, great condition", "price": 45, "pricePennies": 4500, "location": "Salford, Manchester", "ageDays": 0, "isTrade": false, "isFeatured": false, "isDelivery": false, "isGBGVerified": false, "categoryId": 712, "numberOfImages": 3, "hasVideo": false, "position": 5, "recallSource": "primary,queryRewrite", "listingUrl": "https://www.gumtree.com/p/chairs/adjustable-gaming-chair-great-condition/1513777639", "searchKeyword": "gaming chair", "searchLocation": "london", "searchCategory": "furniture-storage", "totalResults": 842, "pageNumber": 1, "scrapedAt": "2025-05-18T10:23:44.123456+00:00" } ``` *** ### Location slugs Find the location slug in the Gumtree URL when you filter by area. Common examples: | Location | Slug | |---|---| | All UK | *(leave blank)* | | London | `london` | | Manchester | `manchester` | | Birmingham | `birmingham` | | Edinburgh | `edinburgh` | | Glasgow | `glasgow` | | Bristol | `bristol` | | Leeds | `leeds` | | Liverpool | `liverpool` | | Sheffield | `sheffield` | | Newcastle | `newcastle` | | Nottingham | `nottingham` | | Cardiff | `cardiff` | | Brighton | `brighton` | To find any location slug: go to gumtree.com, search for something, select your area, then copy the `search_location` value from the URL. *** ### Category slugs Find the category slug in the Gumtree URL when you browse a category. Common examples: | Category | Slug | |---|---| | All categories | *(leave blank)* | | Laptops | `laptops` | | Desktop computers | `desktop-pcs` | | Phones | `phones-mobile-phones` | | Tablets | `tablets-ebooks-readers` | | Cars | `cars-vans` | | Bicycles | `bikes-bicycles` | | Furniture | `furniture-storage` | | Clothing | `clothes` | | Gaming | `video-games-consoles` | | TVs | `televisions` | | Cameras | `cameras` | | Books | `books` | | Tools | `tools-diy` | | Jobs | `jobs` | To find any category slug: go to gumtree.com, browse a category, then copy the path segment after `gumtree.com/` in the URL. *** ### Use cases - **Price monitoring** — track asking prices for any product across the UK or in specific cities over time. Schedule the actor daily or weekly to build a price history. - **Competitor research** — see what trade sellers in your category are listing, at what prices, and how often. - **Lead generation** — filter by `isTrade: true` to find business sellers in specific categories for outreach. - **SEO research** — study listing titles, keyword patterns, and positioning used by high-performing sellers. - **Market analysis** — compare supply and demand across regions. Use `totalResults` to gauge category depth. - **Inventory sourcing** — find underpriced items by filtering `isFeatured: false` and `ageDays: 0`. - **Academic research** — collect secondhand market data for consumer behaviour or pricing studies. *** ### Scheduling To keep your data fresh, schedule the actor in Apify Console: 1. Open the actor and click **Schedules** 2. Set a cron expression (e.g. `0 8 * * *` for every day at 8am) 3. The dataset will append new results each run Useful cron intervals: | Interval | Cron | |---|---| | Every day at 8am | `0 8 * * *` | | Every Monday at 9am | `0 9 * * 1` | | Every 6 hours | `0 */6 * * *` | | Every hour | `0 * * * *` | *** ### Notes - Gumtree is UK only. All prices are in GBP. - Featured listings always appear first regardless of sort order. - The `recallSource` field is absent for featured listings. - A price of 0 means the item is listed as free. - Each search page returns up to 33 listings. The actor pages automatically until `maxItemsPerQuery` is reached or Gumtree has no more pages. - The `ageDays` field is 0 for listings posted today. - `isTrade: true` means the seller is a registered business account. `isTrade: false` is a private individual. - `isGBGVerified` means the seller has passed a GBG identity check (a Gumtree trust feature). - Duplicate listings across combinations are not automatically removed. Use `listingId` to deduplicate in your spreadsheet if needed. *** ### FAQ **How do I find the right location or category slug?** Browse Gumtree normally, apply the filter you want, then look at the URL. The `search_location` and `search_category` parameters are the slugs to use. **Why does the output have more rows than maxItemsPerQuery?** `maxItemsPerQuery` applies per combination. If you have multiple queries or locations, total rows = combinations x maxItemsPerQuery. **Are duplicates possible?** Yes, if the same listing appears in multiple search combinations (e.g. it matches both "laptop" and "macbook" searches). Use `listingId` to deduplicate. **Can I scrape individual listing pages for full descriptions?** This actor collects search result data only. Each result includes a `listingUrl` you can use to scrape the listing detail page separately. **What does recallSource mean?** It is how Gumtree's ranking algorithm categorised the result: `primary` means a direct keyword match, `entity` means a brand/model match, `payShipping` means a delivery listing recalled into local results, and `queryRewrite` means Gumtree broadened the search. # Actor input Schema ## `searchQueries` (type: `array`): One or more keywords to search on Gumtree. Each keyword is scraped separately up to Max items per query. ## `locations` (type: `array`): One or more location slugs to filter results (e.g. london, manchester). Leave empty to search all of the UK. Each location is combined with each search query. ## `categories` (type: `array`): One or more category slugs to narrow results (e.g. laptops, cars). Leave empty to search all categories. Each category is combined with each query and location. ## `maxItemsPerQuery` (type: `integer`): Maximum listings per query/location/category combination. Total output = combinations x this number. Max 500. ## `requestTimeoutSecs` (type: `integer`): Per-request timeout in seconds. ## Actor input object example ```json { "searchQueries": [ "laptop", "macbook", "gaming pc" ], "locations": [ "london", "manchester", "birmingham" ], "categories": [ "laptops", "phones-mobile-phones", "tablets-ebooks-readers" ], "maxItemsPerQuery": 20, "requestTimeoutSecs": 30 } ``` # 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 = { "searchQueries": [ "laptop" ], "locations": [], "categories": [], "maxItemsPerQuery": 20, "requestTimeoutSecs": 30 }; // Run the Actor and wait for it to finish const run = await client.actor("kawsar/gumtree-data-extractor").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 = { "searchQueries": ["laptop"], "locations": [], "categories": [], "maxItemsPerQuery": 20, "requestTimeoutSecs": 30, } # Run the Actor and wait for it to finish run = client.actor("kawsar/gumtree-data-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "laptop" ], "locations": [], "categories": [], "maxItemsPerQuery": 20, "requestTimeoutSecs": 30 }' | apify call kawsar/gumtree-data-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kawsar/gumtree-data-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gumtree Data Extractor", "description": "Gumtree scraper that pulls listing titles, prices, locations, and URLs from search results, so you can track the UK classifieds market without doing it by hand.", "version": "0.0", "x-build-id": "MvCRMiYWOtmFgEWzn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kawsar~gumtree-data-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kawsar-gumtree-data-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/kawsar~gumtree-data-extractor/runs": { "post": { "operationId": "runs-sync-kawsar-gumtree-data-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/kawsar~gumtree-data-extractor/run-sync": { "post": { "operationId": "run-sync-kawsar-gumtree-data-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchQueries": { "title": "Search queries", "type": "array", "description": "One or more keywords to search on Gumtree. Each keyword is scraped separately up to Max items per query.", "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "One or more location slugs to filter results (e.g. london, manchester). Leave empty to search all of the UK. Each location is combined with each search query.", "items": { "type": "string" } }, "categories": { "title": "Categories", "type": "array", "description": "One or more category slugs to narrow results (e.g. laptops, cars). Leave empty to search all categories. Each category is combined with each query and location.", "items": { "type": "string" } }, "maxItemsPerQuery": { "title": "Max items per query", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum listings per query/location/category combination. Total output = combinations x this number. Max 500.", "default": 50 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Per-request timeout in seconds.", "default": 30 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```