carsearch — Kanadische Gebrauchtwagensuche, Monitoring- und Marktanalyse-Plattform

carsearch macht aus kanadischen Marktplatz-Inseraten eine dauerhafte, durchsuchbare, historische Datenbank und stellt sie Claude Code (oder jedem Agenten) über MCP sowie über eine vollständige CLI bereit. Es erfasst echte Inserate von AutoTrader.ca (weitere Anbieter sind anbindbar), speichert jede Preis-/Statusänderung als Historie, dedupliziert physische Fahrzeuge über mehrere Inserate hinweg, geokodiert korrekt (echte Entfernungen), extrahiert Risikosignale aus Beschreibungen, berechnet Vergleichspreis-Statistiken, bewertet Projektwagen anhand konfigurierbarer Profile, erkennt Schnäppchen, führt gespeicherte Suchanfragen planmäßig erneut aus und löst Alerts aus.

Fragen Sie Claude zum Beispiel:

• Finde jeden Schaltwagen-BMW E90 328i unter 8.000 $ innerhalb von 800 km um Toronto, bevorzuge private Verkäufer, lehne Rostlauben ab, sortiere nach Projektwagen-Wert.

• Welche interessanten Projektwagen unter 7.000 $ sind in den letzten 48 Stunden in Ontario aufgetaucht?

• Ist dieser Audi TT für 6.200 $ im Vergleich zu ähnlichen Inseraten, die wir beobachtet haben, tatsächlich günstig?

• Zeig mir alle Preisnachlässe von mehr als 10 % diese Woche. / Autos, die seit 30+ Tagen inseriert sind und bei denen der Verkäufer den Preis bereits zweimal gesenkt hat.

Status pro Phase, getestete Befehle und bekannte Probleme: PROJECT_STATUS.md.

Architektur (kurz)

providers/ (autotrader ✓, cargurus/kijiji/facebook interface+probe)  →  VehicleListing (canonical)
   → collectors/ (checkpointed ProviderRun, ingest w/ snapshots+events, raw payloads)
   → dedupe/ (VIN → weighted soft signals → vehicles + candidates)  → geo/ (geocode, haversine)
   → SQLite/PostgreSQL (SQLAlchemy)  → search/  analysis/ (description, comps, deals, market)
   → scoring/ (profiles + model knowledge JSON)  → monitoring/ (saved searches, scheduler) → notifications/
   → cli/ (carsearch …)  and  mcp/ (23 tools)

Details: docs/architecture.md, docs/providers.md, docs/schema.md.

Installation

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"            # add ".[postgres]" for PostgreSQL
cp .env.example .env               # optional; SQLite in ./data works out of the box
carsearch db-init                  # creates/upgrades data/carsearch.db

Python ≥ 3.11 (entwickelt unter 3.14). Kein Browser, keine API-Schlüssel für AutoTrader erforderlich.

Datenbank-Setup

• Standard: sqlite:///./data/carsearch.db (WAL). Keine weiteren Schritte nötig.

• PostgreSQL: CARSEARCH_DATABASE_URL=postgresql+psycopg://user:pass@host/carsearch in .env, pip install -e ".[postgres]", carsearch db-init. Schema/Migrationen in src/carsearch/database/ (versioniert, erfasst in schema_migrations).

Crawling (Erfassen echter Daten)

# targeted, with detail pages for new listings (VIN, exact coordinates, drivetrain, created date)
carsearch crawl autotrader --make BMW --model "3 Series" --transmission manual --max-price 8000 --min-year 2006 --max-year 2013 --details new
# regional bulk (20 listings/page, ~1.5 s/page, no detail pages)
carsearch crawl autotrader --max-price 7000 --location Toronto --radius-km 500 --max-pages 200 --details none
# province scope (centroid + covering radius server-side, exact province locally)
carsearch crawl autotrader --province ON --transmission manual --max-price 6000 --seller-type private
# incremental refresh: stop after 3 consecutive pages with nothing new/changed
carsearch crawl autotrader --transmission manual --max-price 8000 --stop-when-seen 3
# resume an interrupted run
carsearch crawl autotrader --resume 12
# re-check listings not seen for 3 days (marks removed on 404); fetch missing detail pages; geocode backfill
carsearch refresh autotrader --older-than-days 3 --limit 200
carsearch details autotrader --limit 200
carsearch geocode --limit 60
scripts/bootstrap_crawl.sh   # example multi-band bootstrap used to seed the DB

AutoTrader begrenzt eine Abfrage auf 200 Seiten (4000 Inserate) → für die vollständige Abdeckung nach Preisspanne/Region aufteilen (truncated=True in der Zusammenfassung zeigt Ihnen, wann das nötig ist).

Suche

carsearch search --make BMW --model 328i --max-price 7000 --transmission manual --location Toronto --radius-km 800 --seller-type private
carsearch search --generation E90 --keywords '"one owner" -salvage' --province ON,QC --sort price_asc
carsearch new --since 48h --province ON --max-price 7000
carsearch price-drops --min 10 --since 7d
carsearch deals --province ON --max-price 7000 --profile project_car_enthusiast
carsearch deals --location Toronto --radius-km 500 --transmission manual --max-price 7000 --since 7d \
    --profile project_car_enthusiast --sort-by project --exclude-flags salvage_title,frame_rust,doesnt_run   # "best project cars" ranking
carsearch listing 42            # full record + price history + description flags
carsearch history 42            # snapshots + change events
carsearch comps 42              # comparable-price analysis with methodology
carsearch score 42 --profile project_car_enthusiast
carsearch analyze 42            # everything above + deal signals in one JSON
carsearch market --metric manual_premium --make Subaru --model WRX
carsearch market --metric price_by_mileage --generation E90 --province ON
carsearch market --metric cheapening --days 90
carsearch status [--check-providers]  ·  carsearch runs  ·  carsearch alerts

Jeder Befehl akzeptiert --json für maschinenlesbare Ausgabe.

Monitoring / gespeicherte Suchanfragen / Alerts

carsearch saved seed                       # the four example searches from the brief
carsearch saved create "manual E90 328i under $8k" '{"make":"BMW","model":"3 Series","min_year":2006,"max_year":2011,"max_price":8000,"transmission":"manual"}' \
    --interval-minutes 240 --alert-rules '{"price_drop_pct":10,"target_price":6500,"min_deal_score":65}' --profile project_car_enthusiast
carsearch saved run "manual E90 328i under $8k"   # incremental crawl → new listings + alerts
carsearch schedule                          # long-running loop: runs due searches, maintenance
carsearch schedule --once                   # one pass (cron-friendly)

Alerts gehen an die Konsole, an data/alerts.jsonl und an einen optionalen Webhook (CARSEARCH_WEBHOOK_URL); neue Senken sind Unterklassen von notifications.alerts.AlertSink. Jeder Alert enthält reasons[] (und Risiken).

MCP-Server

carsearch serve-mcp                # stdio (default)  |  --transport streamable-http --port 8765

Tools: search_cars, search_live_marketplace, get_listing, get_vehicle, get_new_listings, get_price_history, get_listing_changes, get_comparables, compare_cars, find_deals, find_price_drops, find_long_sitting_listings, analyze_listing, score_listing, analyze_market, list_saved_searches, create_saved_search, run_saved_search, delete_saved_search, get_alerts, get_status, get_generation_codes, analyze_listing_images. Alle geben strukturiertes JSON mit Paginierung zurück (limit/offset/next_offset); umfangreiche Felder (description, photos, raw) sind opt-in.

Claude Code verbinden

claude mcp add carsearch -- /ABSOLUTE/PATH/autotrader/.venv/bin/carsearch serve-mcp
# or in .mcp.json:
{ "mcpServers": { "carsearch": { "command": "/ABSOLUTE/PATH/autotrader/.venv/bin/carsearch", "args": ["serve-mcp"] } } }

Dann: „Finde die besten Projektwagen mit Handschaltung unter 7.000 $ CAD innerhalb von 500 km um Toronto, die in der letzten Woche erschienen sind. Vergleiche sie mit historischen Preisen, markiere größere mechanische/Rost-Risiken aus den Inseraten und bewerte die Top 10.“ — Claude wird typischerweise search_cars/get_new_listings (oder search_live_marketplace für frische Daten) aufrufen, danach analyze_listing/compare_cars.

Wie Checkpoints funktionieren

Jeder Crawl ist eine provider_runs-Zeile. Nach jeder Seite werden die Inserate committet und last_checkpoint.next_page wird weitergeschaltet; Fehler bei einzelnen Inseraten werden in errors protokolliert und übersprungen. Die Detailanreicherung committet pro Inserat (detail_fetched_at). Ein Lauf, der abbricht, wird zu failed/interrupted, und carsearch crawl --resume <id> setzt bei next_page fort (bereits abgerufene Seiten stammen aus dem lokalen http_cache). Der Zustand der gespeicherten Suchanfragen liegt in der Datenbank. Siehe docs/architecture.md.

So fügen Sie einen Anbieter hinzu

Implementieren Sie BaseProvider in src/carsearch/providers/<name>/, bilden Sie in einem parser.py auf VehicleListing ab (behalten Sie raw), registrieren Sie es, fügen Sie Fixtures + Tests hinzu und dokumentieren Sie es in docs/providers.md. Sonst ändert sich nichts.

Tests

pytest -q          # 42 tests: normalization, parser fixtures, ingest/price history, dedupe,
                   # geo/search, analysis (flags/comps/scoring/deals/market), crawler checkpoints, MCP tools

Kein Test berührt das Netzwerk (echte Payload-Fixtures + ein Fake-Anbieter).

Bekannte Einschränkungen

• Anbieter: Nur AutoTrader.ca sammelt. CarGurus (DataDome), Kijiji (Edge liefert 403 / kijijiautos.ca nicht mehr vorhanden) und Facebook (Login) sind Schnittstellen mit Live-Health-Probes; es werden keine Anti-Bot- oder Login-Umgehungen versucht (siehe docs/providers.md).

• Angebotspreise, keine Verkaufspreise. Verschwinden ≠ verkauft; wir erfassen not_observed/removed.

• Abdeckung hängt davon ab, was Sie crawlen (200-Seiten-Limit pro Abfrage; nach Bändern aufteilen). „Erschienen in den letzten N Tagen“ verwendet das Erstellungsdatum des Marktplatzes, sofern bekannt (Detailseite), sonst unsere erste Beobachtung.

• Koordinaten: exakt für Inserate mit Detailseite; andernfalls auf Stadtebene (Seed-Tabelle / gelernte Zentroide / Marktplatz-Resolver). Entfernungsfilter überspringen Inserate ohne Koordinaten.

• Bewertungen, Flags und Deal-Scores sind Heuristiken mit angegebenen Belegen und konfigurierbaren Regeln (src/carsearch/config/*.json); sie sind Eingaben für die Schlussfolgerung, keine Urteile. Regex-Flags können bei ungewöhnlicher Formulierung fehlschlagen (Belege werden immer zurückgegeben).

• Vergleichswerte verwenden progressive Lockerung; kleine Stichproben werden gekennzeichnet (warnings, confidence).

• Bildanalyse bringt Hashing/Caching und einen anbindbaren Vision-Hook mit (Anthropic-Backend enthalten, standardmäßig deaktiviert); ohne Konfiguration wird kein Vision-Modell ausgeführt.

• SQLite ist für Hunderttausende von Inseraten ausreichend; für gleichzeitige Schreiber auf PostgreSQL umsteigen.