# PistonHeads UK Car Classifieds Scraper (`parseforge/pistonheads-scraper`) Actor Scrape UK performance and enthusiast car listings from PistonHeads.com. Returns prices, mileage, specs, seller details and image galleries. Filter by make, model, price, year, body, fuel. - **URL**: https://apify.com/parseforge/pistonheads-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** E-commerce, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $11.25 / 1,000 records 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 ![ParseForge Banner](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg) ## ๐Ÿ PistonHeads Car Classifieds Scraper > ๐Ÿš€ **Pull UK performance and enthusiast car listings from PistonHeads in seconds.** Filter by make, model, price band, year, mileage, fuel type, body style, and seller type. No API key, no login, no manual CSV wrangling. > ๐Ÿ•’ **Last updated:** 2026-05-16 ยท **๐Ÿ“Š 29 fields** per record ยท **220K+ live listings** ยท **381 makes covered** ยท **JSON / CSV / Excel export** PistonHeads is the UK's home for performance, classic, and enthusiast cars. The site lists everything from a ยฃ1,200 project car to a ยฃ4.8M Ferrari FXX, with a strong mix of specialist independent dealers, marque-authorised retailers, and private sellers. This scraper turns the live PistonHeads classifieds into a structured dataset you can load into a spreadsheet, a notebook, or a database in one run. You give the scraper a search URL or a few filter fields, and it returns every matching listing with prices, mileage, year, specifications (body type, fuel, transmission, colour, engine power and displacement), seller details (name, location, trade or private), pricing model (regular, POA, online auction), and the full gallery of high-resolution images. Behind the scenes it talks to the same JSON search service that powers the PistonHeads buy pages, so the data is identical to what the site shows, just delivered in bulk. | ๐ŸŽฏ Target Audience | ๐Ÿ“Œ Primary Use Cases | |---|---| | Performance and specialist car dealers | Pricing comparisons across rivals and trim levels | | Classic and import brokers | Spotting underpriced cars or import opportunities | | Market researchers and analysts | Tracking depreciation curves on enthusiast segments | | Lead-gen and CRM teams | Building dealer prospect lists with verified locations | | Insurance and warranty firms | Modelling market values for niche makes and models | --- ### ๐Ÿ“‹ What the PistonHeads Scraper does - ๐Ÿท๏ธ **Live classified pricing.** Every active classified, online auction, and price-on-application listing the site exposes today. - ๐Ÿ”Ž **Granular filters.** Make, model keyword, price band, year, mileage, fuel, transmission, body, colour, drivetrain, seller type, postcode radius, and listing type. - ๐Ÿ–ผ๏ธ **Full image galleries.** Both the headline image and the complete `imageUrls` array, ready to embed in a CRM or dashboard. - ๐Ÿข **Dealer vs private split.** A `sellerType` flag plus seller name and location for every record, so you can segment trade and private inventory. - ๐Ÿงญ **URL or form input.** Paste a PistonHeads search URL straight from your browser, or build the query in the structured input fields. - ๐Ÿ† **Auction-aware.** Listings sold via the PistonHeads online auction are flagged with `isAuction` and `pricingModel: OnlineAuction`. Each record contains the listing title and URL, an internal advert id, the price (with a formatted display string and pricing-model code), the make and model, year, mileage, full specification block (body type, colour, fuel, transmission, engine power in bhp, engine displacement in cc), the seller's display name, type (Trade or Private), and location, and the complete gallery of full-size images. A `scrapedAt` ISO timestamp captures when the row was harvested. > ๐Ÿ’ก **Why it matters:** PistonHeads has long been the place where UK enthusiast cars first appear before they hit the wider marketplace. Owning a clean, refreshable dataset of these listings is an edge for dealers, brokers, and analysts who would otherwise be paging through results one screen at a time. --- ### ๐ŸŽฌ Full Demo ๐Ÿšง Coming soon: a 3-minute walkthrough of the input form, a real run, and how to plug the output into Google Sheets or a notebook. --- ### โš™๏ธ Input
FieldTypeDescription
searchUrl string Optional. A PistonHeads.com search URL. Examples: https://www.pistonheads.com/buy/search?priceMax=50000&yearMin=2020 or https://www.pistonheads.com/buy/aston-martin/db9. URL query parameters override the structured filters below.
maxItems integer Cap the number of listings returned. Free plan: capped at 10. Paid plan: up to 1,000,000. Default prefill: 10.
makeUrlName enum (381 values) Manufacturer slug. Picks from every make PistonHeads currently lists, from abarth to zenos.
modelKeyword string Free-text model search (e.g. 911, M3, defender).
priceMin / priceMax integer Asking-price band in GBP.
yearMin / yearMax integer Registration-year band.
mileageMin / mileageMax integer Odometer band in miles.
keywords string Free-text search across headlines (e.g. manual, gt3, one owner).
fuelTypeCodes multi-enum Petrol, Diesel, Electric, Hybrid, LPG, Other.
transmission multi-enum Automatic, Manual, Other.
bodyTypeCodes multi-enum Hatchback, Saloon, Estate, SUV, Coupe, Convertible, MPV, Pick Up, Other.
colourCodes multi-enum 19 colour codes (Black, White, Silver, Grey, Blue, Red, Green, etc.).
driveTrain multi-enum Front-wheel, Rear-wheel, 4-wheel drive, Other.
noDoors / seats multi-enum Door and seat-count filters.
sellerType enum Any, Private, Trade.
postcode / distance string / enum UK postcode plus radius (10, 25, 50, 100, 200 miles, or country wide).
sortOption enum Most relevant, Most recent, Price (low to high / high to low), Distance, Mileage, Year (newest / oldest first).
includeSold boolean Include listings already sold.
pricingModels multi-enum Visible price, On application, Online auction, Auction house.
Example: pull every recent Aston Martin DB-series listing. ```json { "makeUrlName": "aston-martin", "modelKeyword": "db", "yearMin": 2018, "sortOption": "mostRecent", "maxItems": 200 } ```` Example: paste a URL straight from the PistonHeads search page. ```json { "searchUrl": "https://www.pistonheads.com/buy/search?priceMin=10000&priceMax=20000&yearMin=2018&fuelTypeCodes=ELE&sortOption=PriceLowToHigh", "maxItems": 100 } ``` > โš ๏ธ **Good to Know:** URL parameters always win over the structured fields. If you paste a search URL with `priceMax=20000` and also set `priceMax: 50000` in the form, the URL value wins. Leave fields blank if you want the URL to drive the run entirely. *** ### ๐Ÿ“Š Output The dataset contains one row per car listing with 29 structured fields, exportable as JSON, CSV, Excel, or HTML. #### ๐Ÿงพ Schema | Field | Type | Example | |---|---|---| | ๐Ÿ–ผ๏ธ `imageUrl` | string | `https://img.pistonheads.com/Fullsize/.../aston-martin-dbx-dbx707-1441173982-1.jpg` | | ๐Ÿท๏ธ `headline` | string | `Aston Martin DBX DBX707` | | ๐Ÿ”— `url` | string | `https://www.pistonheads.com/buy/listing/20440352` | | ๐Ÿ†” `id` | string | `20440352` | | ๐Ÿ’ท `price` | integer | `174500` | | ๐Ÿฆ `currency` | string | `GBP` | | ๐Ÿท๏ธ `priceLabel` | string | `ยฃ174,500` / `POA` / `Auction: ยฃ22,750` | | ๐Ÿ“ฆ `pricingModel` | string | `Visible` / `OnApplication` / `OnlineAuction` / `AuctionHouse` | | ๐Ÿ“… `year` | integer | `2025` | | ๐Ÿญ `make` | string | `Aston Martin` | | ๐Ÿš— `model` | string | `DBX` | | ๐Ÿ† `brandType` | string | `Core` / `MassMarket` / `Standard` | | ๐Ÿ›ฃ๏ธ `mileage` | integer | `9236` | | โ›ฝ `fuelType` | string | `Petrol` / `Diesel` / `Electric` / `Hybrid` | | โš™๏ธ `transmission` | string | `Automatic` / `Manual` | | ๐Ÿš™ `bodyType` | string | `SUV` / `Coupe` / `Hatchback` / `Saloon` | | ๐ŸŽจ `colour` | string | `Silver` | | ๐ŸŽ๏ธ `enginePower` | integer | `697` (bhp) | | ๐Ÿ”ง `engineSize` | integer | `3982` (cc) | | ๐Ÿข `sellerName` | string | `Stratstone Aston Martin Manchester` | | ๐Ÿ‘ฅ `sellerType` | string | `Trade` / `Private` | | ๐Ÿ“ `sellerLocation` | string | `Wilmslow, United Kingdom` | | ๐ŸŒ `sellerIsOnlineRetailer` | boolean | `false` | | ๐Ÿ”จ `isAuction` | boolean | `true` for online or house auctions | | ๐Ÿท๏ธ `isPriceOnApplication` | boolean | `true` when price is hidden | | ๐Ÿงพ `isVatOmitted` | boolean | `false` | | ๐Ÿ… `badges` | string\[] | `["Delivery", "ClickAndCollect"]` | | ๐Ÿ–ผ๏ธ `imageUrls` | string\[] | Full gallery of high-res images | | โฑ๏ธ `scrapedAt` | ISO timestamp | `2026-05-16T14:43:08.821Z` | #### ๐Ÿ“ฆ Sample records
๐ŸŸข Typical: a current franchise-dealer listing ```json { "imageUrl": "https://img.pistonheads.com/Fullsize/aston-martin/dbx/dbx707/aston-martin-dbx-dbx707-1441173982-1.jpg", "headline": "Aston Martin DBX DBX707", "url": "https://www.pistonheads.com/buy/listing/20440352", "id": "20440352", "price": 174500, "currency": "GBP", "priceLabel": "ยฃ174,500", "pricingModel": "Visible", "year": 2025, "make": "Aston Martin", "model": "DBX", "brandType": "Core", "mileage": 9236, "fuelType": "Petrol", "transmission": "Automatic", "bodyType": "SUV", "colour": "Silver", "enginePower": 697, "engineSize": 3982, "sellerName": "Stratstone Aston Martin Manchester", "sellerType": "Trade", "sellerLocation": "Wilmslow, United Kingdom", "sellerIsOnlineRetailer": false, "isAuction": false, "isPriceOnApplication": false, "isVatOmitted": false, "badges": ["Delivery", "ClickAndCollect"], "imageUrls": [ "https://img.pistonheads.com/Fullsize/aston-martin/dbx/dbx707/aston-martin-dbx-dbx707-1441173982-1.jpg", "https://img.pistonheads.com/Fullsize/aston-martin/dbx/dbx707/aston-martin-dbx-dbx707-1441173982-2.jpg" ], "scrapedAt": "2026-05-16T14:43:08.821Z" } ```
๐Ÿ† Edge case: a multi-million-pound classic with sparse spec data ```json { "imageUrl": "https://img.pistonheads.com/Fullsize/ferrari/275-gts/ferrari-275-gts-1436111905-1.jpg", "headline": "1965 Ferrari 275 GTS by Pininfarina", "url": "https://www.pistonheads.com/buy/listing/19608359", "id": "19608359", "price": 1600000, "currency": "EUR", "priceLabel": "ยฃ1,600,000", "pricingModel": "Visible", "year": 1965, "make": "Ferrari", "model": "275", "brandType": "Core", "mileage": null, "fuelType": null, "transmission": null, "bodyType": "Unknown", "colour": "", "enginePower": null, "engineSize": null, "sellerName": "RM Sothebys UK", "sellerType": "Trade", "sellerLocation": "Richmond, United Kingdom", "sellerIsOnlineRetailer": false, "isAuction": false, "isPriceOnApplication": false, "isVatOmitted": false, "badges": [], "imageUrls": [ "https://img.pistonheads.com/Fullsize/ferrari/275-gts/ferrari-275-gts-1436111905-1.jpg", "https://img.pistonheads.com/Fullsize/ferrari/275-gts/ferrari-275-gts-1436111905-2.jpg" ], "scrapedAt": "2026-05-16T14:37:40.088Z" } ```
โšช Sparse: a brand-new dealer listing missing some classified spec values ```json { "imageUrl": "https://img.pistonheads.com/Fullsize/volkswagen/t-roc/1-5-tsi-black-edition-plus-5dr/volkswagen-t-roc-1-5-tsi-black-edition-plus-5dr-1441172200-1.jpg", "headline": "Volkswagen T-Roc 1.5 TSI Black Edition Plus 5dr", "url": "https://www.pistonheads.com/buy/listing/20440342", "id": "20440342", "price": 27489, "currency": "GBP", "priceLabel": "ยฃ27,489", "pricingModel": "Visible", "year": 2025, "make": "Volkswagen", "model": "T-Roc", "brandType": "MassMarket", "mileage": 2128, "fuelType": null, "transmission": "Manual", "bodyType": "Hatchback", "colour": "White", "enginePower": null, "engineSize": 1498, "sellerName": "Wrexham Volkswagen", "sellerType": "Trade", "sellerLocation": "Gwersyllt, United Kingdom", "sellerIsOnlineRetailer": false, "isAuction": false, "isPriceOnApplication": false, "isVatOmitted": false, "badges": [], "imageUrls": [ "https://img.pistonheads.com/Fullsize/volkswagen/t-roc/1-5-tsi-black-edition-plus-5dr/volkswagen-t-roc-1-5-tsi-black-edition-plus-5dr-1441172200-1.jpg", "https://img.pistonheads.com/Fullsize/volkswagen/t-roc/1-5-tsi-black-edition-plus-5dr/volkswagen-t-roc-1-5-tsi-black-edition-plus-5dr-1441172200-2.jpg" ], "scrapedAt": "2026-05-16T14:43:08.821Z" } ```
*** ### โœจ Why choose this Actor | โœจ | Capability | |---|---| | ๐Ÿ‡ฌ๐Ÿ‡ง | **UK enthusiast focus.** Built around the niche PistonHeads catalogues that wider classifieds tools miss. | | ๐ŸŽฏ | **All 21 filters mapped.** Every knob the site exposes is in the input schema, no invented or missing fields. | | ๐Ÿ“š | **381-make enum.** Every manufacturer slug PistonHeads validates, from Abarth to Zenos, presented as a dropdown, not free text. | | ๐Ÿ–ผ๏ธ | **High-resolution galleries.** The full image array per listing, not just a thumbnail. | | ๐Ÿ”จ | **Auction-aware output.** Online auctions, auction-house lots, and POA listings are flagged separately. | | ๐Ÿงช | **Pure API path.** Talks to the site's own JSON search service. No browser, no captchas, fast and stable. | | ๐Ÿ’ท | **Predictable pricing.** Pay per usage on Apify, with a free-tier preview of 10 items. | > ๐Ÿ“Š 220,000+ listings across 381 makes and 2,000+ models indexed at the time of writing. Refresh as often as your workflow requires. *** ### ๐Ÿ“ˆ How it compares to alternatives | Approach | Cost | Coverage | Refresh | Filters | Setup | |---|---|---|---|---|---| | **โญ PistonHeads Scraper** *(this Actor)* | Pay per use | Live PistonHeads catalogue, 220K+ rows | On demand | 21 filters, 381 makes | 30 seconds in the Apify console | | Official site CSV exports | Not offered | n/a | n/a | n/a | n/a | | Paid live APIs from data resellers | Per-row subscription | Aggregated, sometimes stale | Daily batch | Limited | Contract signing, integration work | | Manual copy / paste from the browser | Free | One listing at a time | Manual | All site filters | Hours per study | | In-house scraper | Engineering salary | Whatever you scope | DIY | Whatever you scope | Days to build, ongoing maintenance | Pick the row that matches how much custom plumbing you want to own. *** ### ๐Ÿš€ How to use 1. ๐Ÿ†• **Open a free Apify account.** Sign up at [console.apify.com/sign-up?fpr=vmoqkp](https://console.apify.com/sign-up?fpr=vmoqkp). 2. ๐Ÿ” **Find the actor.** Search "PistonHeads" in the Apify Store and open this actor's page. 3. โš™๏ธ **Set your filters.** Either paste a PistonHeads search URL or pick make, price band, year, and sort order in the form. 4. โ–ถ๏ธ **Run.** Click Start. The default preview run returns 10 listings on the free plan, up to 1,000,000 on a paid plan. 5. ๐Ÿ’พ **Export.** Download the dataset as JSON, CSV, Excel, or HTML, or read it through the Apify API. > โฑ๏ธ **Total time:** less than a minute from "I need this data" to a downloadable spreadsheet. *** ### ๐Ÿ’ผ Business use cases
#### ๐Ÿช Specialist dealers and brokers - Track competitor pricing on the exact trims you stock - Build dynamic "missing inventory" alerts on rare models - Identify undervalued cars to source before they sell - Benchmark your asking prices against the live market #### ๐Ÿ“Š Market analysts and consultancies - Run depreciation analyses on enthusiast segments - Track regional price spreads using postcode radius filters - Build supply curves by make, year, and bodystyle - Quote market values for valuations and warranties
#### ๐ŸŒ Import and export specialists - Spot UK-spec cars priced below comparable European listings - Monitor RHD inventory for export to right-hand-drive markets - Filter by spec and trim to satisfy specific customer briefs - Build watchlists for trade buyers in Hong Kong, UAE, or Japan #### ๐Ÿ“ฃ Marketing and lead generation - Generate dealer prospect lists with verified UK locations - Power "cars in your area" feeds for affiliate sites - Enrich CRM records with current asking-price benchmarks - Build retargeting audiences off listing make / model / price bands
*** ### ๐ŸŒŸ Beyond business use cases Data like this powers more than commercial workflows. The same structured records support research, education, civic projects, and personal initiatives.
#### ๐ŸŽ“ Research and academia - Empirical datasets for papers, thesis work, and coursework - Longitudinal studies tracking changes across snapshots - Reproducible research with cited, versioned data pulls - Classroom exercises on data analysis and ethical scraping #### ๐ŸŽจ Personal and creative - Side projects, portfolio demos, and indie app launches - Data visualizations, dashboards, and infographics - Content research for bloggers, YouTubers, and podcasters - Hobbyist collections and personal trackers
#### ๐Ÿค Non-profit and civic - Transparency reporting and accountability projects - Advocacy campaigns backed by public-interest data - Community-run databases for local issues - Investigative journalism on public records #### ๐Ÿงช Experimentation - Prototype AI and machine-learning pipelines with real data - Validate product-market hypotheses before engineering spend - Train small domain-specific models on niche corpora - Test dashboard concepts with live input
*** ### ๐Ÿ”Œ Automating PistonHeads Scraper You do not need to babysit the actor. Trigger it on a schedule, from a webhook, or from your own code. - **Node.js:** install [`apify-client`](https://docs.apify.com/api/client/js/) and call `client.actor('parseforge/pistonheads-scraper').call({ ... })`. - **Python:** install [`apify-client`](https://docs.apify.com/api/client/python/) and call `client.actor('parseforge/pistonheads-scraper').call({ ... })`. - **REST and webhooks:** see the [Apify API reference](https://docs.apify.com/api/v2) for run-and-poll, run-sync, and webhook patterns. Use Apify Schedules to run the actor every hour, every morning, or once a week and have the dataset flow straight into your warehouse, Sheet, or notebook. *** ### โ“ Frequently Asked Questions
๐Ÿค” What exactly does this scraper return? Every active PistonHeads classified that matches your filters, with 29 structured fields per row (price, mileage, year, full spec block, seller details, gallery images, pricing model, and a scrape timestamp). It uses the same JSON search service that powers the PistonHeads buy pages, so the data is identical to what the site shows.
๐ŸŒ Can I paste any PistonHeads URL? Yes for `/buy/search?...` query-string URLs and SEO-friendly URLs like `/buy/aston-martin` or `/buy/aston-martin/db9`. The scraper parses the path and the query string and resolves makes and models to internal ids. Individual listing pages (`/buy/listing/{id}`) are not supported as input.
๐Ÿ”ข How big can a single run be? Up to 1,000,000 listings per run on a paid plan. PistonHeads typically lists 200,000 to 230,000 active cars at any time, so most paid runs cover the entire site.
๐Ÿ†“ What does the free plan include? Free runs return up to 10 items so you can preview the schema and confirm fit before committing. Upgrade to any paid Apify plan for unrestricted output.
๐Ÿ›ก๏ธ How is anti-bot handled? The scraper talks to the site's official JSON search endpoint that powers its own buy pages. There is no headless browser, no captcha, and no IP rotation needed for typical runs. If the site changes its endpoint, this actor is updated to match.
๐Ÿ”„ How fresh is the data? Every run hits the live site. Run the actor whenever you need a refresh: hourly, daily, weekly. Apify Schedules can do this for you automatically.
๐Ÿ“ค What output formats are supported? JSON, CSV, Excel (`xlsx`), HTML, JSONL, RSS, and XML. All are available from the Apify console or the dataset API.
๐Ÿท๏ธ Why is `fuelType` sometimes null on brand-new listings? Some very new dealer listings have not been fully classified by PistonHeads yet. The scraper returns exactly what the source returns at the moment of the run. Re-run the actor a day or two later and the field is usually populated.
๐Ÿข Is this data OK for commercial use? The scraper collects public listing data that PistonHeads publishes for buyers. Your usage of that data is your responsibility. Review the [PistonHeads terms of use](https://www.pistonheads.com/terms-of-use) before using the data in a commercial product, and consult a lawyer for jurisdiction-specific guidance.
๐Ÿ’ณ Do I need a paid Apify plan? No, you can start on the free plan and pull 10-item previews indefinitely. Upgrade only when you want larger runs or scheduled jobs.
๐Ÿšจ What happens if a run fails? Failed runs are visible in your Apify console with full logs. Common causes are invalid input (e.g. mistyped make slug). The actor pushes an explanatory `{ error: ... }` row into the dataset when it cannot proceed, so you always know what went wrong. You are not charged for error rows.
โš–๏ธ Is web scraping legal? In most jurisdictions, scraping publicly accessible data is legal, but the rules vary and depend on what you do with the data. Always review the target site's terms of use, respect rate limits, and consult legal counsel for high-stakes use cases. See the [Apify legal overview](https://docs.apify.com/legal) for general guidance.
*** ### ๐Ÿ”Œ Integrate with any app - [**Apify API**](https://docs.apify.com/api/v2) - Run the actor, fetch datasets, manage schedules over HTTP. - [**Apify Node.js client**](https://docs.apify.com/api/client/js/) - Trigger runs and stream results from JavaScript or TypeScript. - [**Apify Python client**](https://docs.apify.com/api/client/python/) - Same idea for Python notebooks and pipelines. - [**Webhooks**](https://docs.apify.com/platform/integrations/webhooks) - Get notified when a run finishes and push the data straight into your stack. - [**Apify integrations**](https://docs.apify.com/platform/integrations) - Native connectors for Zapier, Make, Slack, Google Drive, Gmail, and more. - [**Schedules**](https://docs.apify.com/platform/schedules) - Cron-style automation so your dataset is always up to date. *** ### ๐Ÿ”— Recommended Actors - [**๐Ÿš™ Autotrader Scraper**](https://apify.com/parseforge/autotrader-scraper) - Pull listings from the largest UK and US used-car classifieds platform. - [**๐Ÿ“ฐ Gumtree Cars Scraper**](https://apify.com/parseforge/gumtree-cars-scraper) - UK private and trade classifieds with prices, specs, and seller info. - [**๐Ÿ”จ Cars & Bids Scraper**](https://apify.com/parseforge/carsandbids-scraper) - Online auction data for modern enthusiast cars. - [**๐ŸŒ JamesEdition Cars Listings**](https://apify.com/parseforge/james-edition-cars-scraper) - Global luxury and supercar marketplace data. - [**๐Ÿ“‹ CARFAX Used Cars Scraper**](https://apify.com/parseforge/carfax-scraper) - Used-car listings paired with vehicle-history context. > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge) for more scrapers covering automotive, real estate, marketplaces, and lead generation. *** **๐Ÿ†˜ Need Help?** [**Open our contact form**](https://tally.so/r/BzdKgA) and we will get back to you within one business day. *** > โš–๏ธ **Disclaimer:** This actor accesses publicly available content from PistonHeads.com. It is not affiliated with, endorsed by, or sponsored by PistonHeads or any of its parent companies. Use it in line with the site's terms of use and the laws of your jurisdiction. The actor authors take no responsibility for downstream use of the collected data. # Actor input Schema ## `searchUrl` (type: `string`): Paste a PistonHeads.com search URL to use the exact filters from your browser. Examples: https://www.pistonheads.com/buy/search?priceMax=50000\&yearMin=2020 or https://www.pistonheads.com/buy/aston-martin/db9. Leave blank to use the filter fields below. ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000 ## `makeUrlName` (type: `string`): Filter listings by manufacturer (e.g. aston-martin, porsche, bmw). ## `modelKeyword` (type: `string`): Filter by model name (free-text keyword search). Examples: '911', 'M3', 'Defender'. ## `priceMin` (type: `integer`): Minimum asking price in pounds. ## `priceMax` (type: `integer`): Maximum asking price in pounds. ## `yearMin` (type: `integer`): Earliest registration year. ## `yearMax` (type: `integer`): Latest registration year. ## `mileageMin` (type: `integer`): Minimum odometer reading in miles. ## `mileageMax` (type: `integer`): Maximum odometer reading in miles. ## `keywords` (type: `string`): Free-text keyword search in headlines and listings (e.g. 'manual', 'rs', 'gt3'). ## `fuelTypeCodes` (type: `array`): Filter by fuel type. Multi-select allowed. ## `transmission` (type: `array`): Filter by gearbox type. Multi-select allowed. ## `bodyTypeCodes` (type: `array`): Filter by body style. Multi-select allowed. ## `colourCodes` (type: `array`): Filter by exterior colour. Multi-select allowed. ## `driveTrain` (type: `array`): Filter by drivetrain layout. Multi-select allowed. ## `noDoors` (type: `array`): Filter by number of doors. ## `seats` (type: `array`): Filter by number of seats. ## `sellerType` (type: `string`): Filter by seller category. ## `postcode` (type: `string`): UK postcode for distance-based search (use together with the Distance field). ## `distance` (type: `string`): Search radius around the postcode in miles. ## `sortOption` (type: `string`): Sort order of the results. ## `includeSold` (type: `boolean`): Include listings that are already sold. ## `pricingModels` (type: `array`): Restrict to specific listing types (auctions, classifieds, or part-exchange). ## Actor input object example ```json { "maxItems": 10, "distance": "", "sortOption": "mostRelevant", "includeSold": false } ``` # Actor output Schema ## `cars` (type: `string`): Full dataset with all scraped car listings. ## `overview` (type: `string`): Overview view with key fields in a table layout. # 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 = { "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/pistonheads-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "maxItems": 10 } # Run the Actor and wait for it to finish run = client.actor("parseforge/pistonheads-scraper").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 '{ "maxItems": 10 }' | apify call parseforge/pistonheads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/pistonheads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "PistonHeads UK Car Classifieds Scraper", "description": "Scrape UK performance and enthusiast car listings from PistonHeads.com. Returns prices, mileage, specs, seller details and image galleries. Filter by make, model, price, year, body, fuel.", "version": "0.0", "x-build-id": "sSTs2p6rNm1e0kbLZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~pistonheads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-pistonheads-scraper", "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/parseforge~pistonheads-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-pistonheads-scraper", "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/parseforge~pistonheads-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-pistonheads-scraper", "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": { "searchUrl": { "title": "Search URL (optional)", "type": "string", "description": "Paste a PistonHeads.com search URL to use the exact filters from your browser. Examples: https://www.pistonheads.com/buy/search?priceMax=50000&yearMin=2020 or https://www.pistonheads.com/buy/aston-martin/db9. Leave blank to use the filter fields below." }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000" }, "makeUrlName": { "title": "Make", "enum": [ "abarth", "ac", "adler", "ajs", "alfa-romeo", "allard", "alpina", "alpine", "alta", "alvis", "american-motors", "amilcar", "amphicar", "andre", "ariel", "arkley", "armstrong-siddeley", "arrol-aster", "asaido", "ascari", "ascot", "aston-martin", "atalanta", "auburn", "audi", "austin", "austin-healey", "austro-daimler", "autocraft", "autovia", "bac", "ballot", "bantam", "batten", "bedford", "bentley", "berkeley", "beverley", "bianchi", "bike-powered-cars", "bitter", "bizzarrini", "bmw", "bond", "borgward", "boring-stuff", "bowler", "brabham", "bristol", "britannia", "british-salmson", "brooke", "brough-superior", "buckler", "bugatti", "buick", "burney", "byd", "cadillac", "caparo", "carver", "caterham", "chenard-walcker", "chevrolet", "chrysler", "cisitalia", "citroen", "clan", "cleco", "clement", "colt", "connaught", "cord", "cornet", "costin", "coventry-victor", "cransac", "crossley", "cupra", "dacia", "daewoo", "daf", "daihatsu", "daimler", "darracq", "datsun", "davarian", "de-soto", "de-tomaso", "delage", "delahaye", "delaunay-belleville", "dellow", "delorean", "denza", "derby", "dkw", "dodge", "donnet", "dri-sleeve", "ds-automobiles", "duesenberg", "dutton", "elemental", "elva", "enfield", "erskine", "essex", "evante", "excalibur", "excelsior", "facel-vega", "fairthorpe", "falcon", "farbio", "ferrari", "fiat", "fisker", "ford", "franklin", "frazer-nash", "frazer-tickford", "frisky", "gardner-douglas", "gb-roadster", "genesis", "georges-irat", "gilbern", "ginetta", "gitane", "gk", "glas", "gmc", "graham", "great-british-sports-cars", "great-wall", "grinnall", "gsm", "gumpert", "hampton", "hansa", "healey", "heinkel", "heron", "hillman", "hispano-suiza", "hmc", "holden", "hommell", "honda", "horch", "hotchkiss", "hrg", "hudson", "humber", "hummer", "hupmobile", "hyundai", "imperia", "ineos", "infiniti", "innocenti", "invicta", "iso", "isotta-fraschini", "isuzu", "itala", "iveco", "jaguar", "javan", "jeep", "jensen", "jewel", "jmb", "jouffret", "jowett", "kia", "kieft", "kit-cars", "koenigsegg", "ktm", "la-salle", "lada", "lagonda", "lamborghini", "lammas", "lanchester", "lancia", "land-rover", "lavie", "lea-francis", "left-hand-drive", "leidart", "lexus", "leyland", "light-car-company", "lincoln", "lister", "lloyd", "lmb", "lola", "london-taxis-international", "lorraine-dietrich", "lotus", "lpg-alternative-fuels", "man", "marauder", "marcos", "marendaz", "marlin", "marmon", "marquette", "maserati", "mathis", "matra", "matra-simca", "maxus", "maxwell", "maybach", "mazda", "mclaren", "mercedes-benz", "mercury", "messerschmitt", "metropolitan", "mg", "micro", "midas", "minerva", "mini", "mini-classic", "mini-marcos", "minijem", "mitsubishi", "mitsuoka", "monica", "monteverdi", "moon", "morgan", "morris", "moskvich", "mosler", "moveo", "mst", "nash", "nash-healey", "nissan", "noble", "nsu", "ogle", "oldsmobile", "om", "opel", "opperman", "opus-hrf", "other-makes", "packard", "pagani", "panhard", "panther", "paramount", "peel", "peerless", "peugeot", "peykan", "pgo", "pierce-arrow", "piper", "plymouth", "polestar", "polski-fiat", "pontiac", "porsche", "powerdrive", "princess", "prodrive", "proton", "puma", "qoros", "quadzilla", "radical", "railton", "ram-trucks", "rapier", "reliant", "renault", "reo", "replica", "rhode", "riley", "rimac", "rivian", "rochdale", "rochet-schneider", "rockne", "rodley", "rolls-royce", "rover", "russon", "rytecraft", "saab", "salmson", "saturn", "scootacar", "scorpion", "seat", "sebring", "secma", "shelby", "siata", "simca", "singer", "skoda", "smart-car", "spartan", "spectre", "speedwell", "spire", "spyker", "squire", "ss", "ssangyong", "standard", "star", "stealth", "steyr", "steyr-puch", "strathcarron", "studebaker", "stutz", "subaru", "sunbeam", "superformance", "suzuki", "swallow", "swift", "talbot", "talbot-lago", "tata", "tatra", "terraplane", "tesla", "tiger", "tojeiro", "tommykaira", "tornado", "tourette", "toyota", "trabant", "tracta", "trident", "triumph", "trojan", "turner", "tvr", "ultima", "unipower", "vale-special", "vanden-plas", "vauxhall", "venturi", "veritas", "vignale-fiat", "voisin", "volga", "volkswagen", "volvo", "vuhl", "wanderer", "wartburg", "warwick", "westfield", "whitlock", "wiesmann", "william", "willys", "willys-knight", "wolseley", "zagato", "zaporozhets", "zenos" ], "type": "string", "description": "Filter listings by manufacturer (e.g. aston-martin, porsche, bmw)." }, "modelKeyword": { "title": "Model keyword", "type": "string", "description": "Filter by model name (free-text keyword search). Examples: '911', 'M3', 'Defender'." }, "priceMin": { "title": "Minimum price (GBP)", "minimum": 0, "type": "integer", "description": "Minimum asking price in pounds." }, "priceMax": { "title": "Maximum price (GBP)", "minimum": 0, "type": "integer", "description": "Maximum asking price in pounds." }, "yearMin": { "title": "Minimum year", "minimum": 1900, "maximum": 2100, "type": "integer", "description": "Earliest registration year." }, "yearMax": { "title": "Maximum year", "minimum": 1900, "maximum": 2100, "type": "integer", "description": "Latest registration year." }, "mileageMin": { "title": "Minimum mileage", "minimum": 0, "type": "integer", "description": "Minimum odometer reading in miles." }, "mileageMax": { "title": "Maximum mileage", "minimum": 0, "type": "integer", "description": "Maximum odometer reading in miles." }, "keywords": { "title": "Keywords", "type": "string", "description": "Free-text keyword search in headlines and listings (e.g. 'manual', 'rs', 'gt3')." }, "fuelTypeCodes": { "title": "Fuel type", "type": "array", "description": "Filter by fuel type. Multi-select allowed.", "items": { "type": "string", "enum": [ "PTL", "DSL", "ELE", "HYB", "LPG", "OTH" ], "enumTitles": [ "Petrol", "Diesel", "Electric", "Hybrid", "LPG", "Other" ] } }, "transmission": { "title": "Transmission", "type": "array", "description": "Filter by gearbox type. Multi-select allowed.", "items": { "type": "string", "enum": [ "ATO", "MAN", "OTH" ], "enumTitles": [ "Automatic", "Manual", "Other" ] } }, "bodyTypeCodes": { "title": "Body type", "type": "array", "description": "Filter by body style. Multi-select allowed.", "items": { "type": "string", "enum": [ "CON", "COU", "EST", "SUV", "HTC", "SAL", "MPV", "PKU", "OTH" ], "enumTitles": [ "Convertible", "Coupe", "Estate", "SUV", "Hatchback", "Saloon", "MPV", "Pick Up", "Other" ] } }, "colourCodes": { "title": "Colour", "type": "array", "description": "Filter by exterior colour. Multi-select allowed.", "items": { "type": "string", "enum": [ "BLA", "BLU", "GRN", "GRY", "RED", "SIL", "WHI", "YEL", "BEI", "BRO", "BRZ", "CRE", "GOL", "MAR", "MUL", "ORA", "PNK", "PPL", "TUR" ], "enumTitles": [ "Black", "Blue", "Green", "Grey", "Red", "Silver", "White", "Yellow", "Beige", "Brown", "Bronze", "Cream", "Gold", "Maroon", "Multi colour", "Orange", "Pink", "Purple", "Turquoise" ] } }, "driveTrain": { "title": "Drivetrain", "type": "array", "description": "Filter by drivetrain layout. Multi-select allowed.", "items": { "type": "string", "enum": [ "FRO", "REA", "AWD", "OTH" ], "enumTitles": [ "Front-wheel drive", "Rear-wheel drive", "4-wheel drive", "Other" ] } }, "noDoors": { "title": "Number of doors", "type": "array", "description": "Filter by number of doors.", "items": { "type": "string", "enum": [ "002", "003", "004", "005", "006" ], "enumTitles": [ "2", "3", "4", "5", "6" ] } }, "seats": { "title": "Number of seats", "type": "array", "description": "Filter by number of seats.", "items": { "type": "string", "enum": [ "2", "3", "4", "5", "6", "7", "8", "9" ], "enumTitles": [ "2", "3", "4", "5", "6", "7", "8", "9" ] } }, "sellerType": { "title": "Seller type", "enum": [ "", "Private", "Trade" ], "type": "string", "description": "Filter by seller category." }, "postcode": { "title": "Postcode", "type": "string", "description": "UK postcode for distance-based search (use together with the Distance field)." }, "distance": { "title": "Distance from postcode", "enum": [ "", "10", "25", "50", "100", "200" ], "type": "string", "description": "Search radius around the postcode in miles.", "default": "" }, "sortOption": { "title": "Sort order", "enum": [ "mostRelevant", "mostRecent", "priceAsc", "priceDesc", "distance", "mileage", "yearDesc", "yearAsc" ], "type": "string", "description": "Sort order of the results.", "default": "mostRelevant" }, "includeSold": { "title": "Include sold cars", "type": "boolean", "description": "Include listings that are already sold.", "default": false }, "pricingModels": { "title": "Listing type", "type": "array", "description": "Restrict to specific listing types (auctions, classifieds, or part-exchange).", "items": { "type": "string", "enum": [ "Visible", "OnApplication", "OnlineAuction", "AuctionHouse" ], "enumTitles": [ "Visible price", "Price on application", "Online auction", "Auction house" ] } } } }, "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 } } } } } } } } } } ```