Ultimate Scraper Cars Actor (Apify)

Scrape used car listings from major car marketplaces across many countries and return structured rows to the Apify dataset.

Quick Start (Recommended)

For most users, only set these fields:

• countries or websites
• brandQuery (optional)
• modelQuery (optional)
• pagesPerRun
• maxListings

Example: run a simple Toyota search in Australia.

{
  "countries": ["AU"],
  "brandQuery": "Toyota",
  "pagesPerRun": 2,
  "maxListings": 50
}

Example: run specific websites only.

{
  "websites": ["truecarus", "carscomus", "carmaxus"],
  "brandQuery": "Honda",
  "pagesPerRun": 1,
  "maxListings": 40
}

Input Guide

1) Pick where to scrape

• websites: explicit website list.
• countries: all websites in those countries.
• If both are provided, countries narrows the selected websites.

2) Add optional filters

• brandQuery: single brand, easiest brand filter input.
• modelQuery: single model.
• yearMin, yearMax, minPrice, maxPrice: optional numeric filters.

3) Control run size

• pagesPerRun: pages per source for this run.
• maxListings: max output rows per source (0 = unlimited).
• sourceConcurrency: how many sources run in parallel inside one actor run.

Advanced tuning is still supported through API/raw JSON input, but hidden in the default Apify form to keep onboarding simple.

Output Fields

Core output fields:

• source, source_site
• country_code, country_name, currency_code
• listing_id, url, title
• price, year, brand, model, mileage_km

Additional fields may include:

• drivetrain/spec fields (fuel, transmission, engine_size_cc, etc.)
• seller/location fields (dealer, location)
• metadata (listing_status, scraped_at, raw_detail)

Apify metadata lives in:

• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/.actor/actor.json

Schema files are mirrored in both locations and kept in sync by tests:

• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/input_schema.json
• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/output_schema.json
• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/dataset_schema.json
• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/.actor/input_schema.json
• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/.actor/output_schema.json
• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/.actor/dataset_schema.json

Brand Matching Behavior

• brandQuery="VW" matches Volkswagen.
• Brand filtering is enforced on final output rows.
• For supported sources, brand pre-filters are also pushed upstream to reduce off-brand scraping.
• Known single-brand sources are skipped when they cannot match your selected brand.

Billing (Pay Per Event)

The actor always emits these event names:

• result (per output row)
• website_search (per source searched)

In Apify Store pricing, configure the same event names.

Troubleshooting

If output is empty:

• Increase pagesPerRun (for example from 1 to 3).
• Remove strict filters (modelQuery, price/year ranges) and retry.
• Use websites directly to test one source at a time.
• Some websites may need proxies due anti-bot protection.

If runs are slow:

• Reduce number of websites.
• Lower pagesPerRun.
• Keep includeRawDetail=false.
• Increase sourceConcurrency gradually.

Local Run

cd Actors/cars
pip install -r requirements.txt
mkdir -p storage/key_value_stores/default
cp input.example.json storage/key_value_stores/default/INPUT.json
python src/main.py

Smoke Tests

python scripts/smoke_cars_sources.py --config scraper_config.yaml --pages 1 --max-listings 5
python scripts/smoke_cars_brand_filter.py --config scraper_config.yaml --pages 1 --max-listings 12

Full Source List

The source registry is maintained in:

• /Users/inusgrobler/Documents/AAComputer Science/Coding Projects/2026/the-ultimate-scraper/Actors/cars/registry.py