Technische Dokumentation
Überblick
Die Potential-Suche kombiniert die Google Places API, ein eigenes Web-Scraping und das KI-Modell Claude (claude-opus-4-7), um Unternehmen in einer Region automatisch nach ihrem Potential zu bewerten. Der gesamte Ablauf läuft als Hintergrundjob — die UI pollt alle 1,5 Sekunden den Fortschritt.
Ablauf im Detail
Claude generiert aus dem eingegebenen Thema und der Art des Potentials automatisch 5–12 deutschsprachige Google-Maps-Suchbegriffe. Diese werden als Tags in die Suche übernommen und können manuell ergänzt oder gelöscht werden.
POST /api/keywords → string[]
Für jede Kombination aus Suchbegriff × Region wird die Google Places API (New) abgefragt (searchText-Endpoint). Pro Kombination werden bis zu 20 Treffer geladen. Alle Ergebnisse werden anhand der place_id dedupliziert.
Überschreitet die Gesamtmenge das Max. Treffer-Limit, wird nach Google-Bewertung (Rating × Anzahl Bewertungen) abgeschnitten.
Parallelität: 3 gleichzeitige Anfragen
Für alle Unternehmen mit bekannter Website wird die Homepage abgerufen. Extrahiert werden:
- E-Mail-Adressen — aus sichtbarem Text, HTML-Attributen und verlinkten Kontaktseiten (bis zu 4 Unterseiten), inkl. Erkennung von obfuskierten Adressen (
[at],(dot)etc.) - Kurzbeschreibung — Meta-Description, OG-Description oder Seitentitel
- Volltext — für den Must-Have-Check (wird nicht gespeichert)
Ist ein Must-Have-Begriff im Volltext nicht enthalten, wird das Unternehmen sofort als LOW markiert und das Claude-Scoring übersprungen. Gleiches gilt für Unternehmen ohne Website wenn Must-Haves definiert sind.
Parallelität: 6 gleichzeitige Anfragen
Claude bewertet jedes verbleibende Unternehmen anhand von Name, Adresse, Google-Kategorien und der gescrapten Beschreibung. Das Ergebnis ist eines von drei Levels:
Claude berücksichtigt dabei alle vier Steuerungsfelder:
- Art des Potentials — was genau gesucht wird
- Ausschlusskriterien — Unternehmen die passen → LOW
- Weitere Kriterien — zusätzliche Anforderungen
- Must-Have auf Webseite — harte Textprüfung vor Claude (spart Tokens)
Jede Anfrage liefert zusätzlich eine kurze Begründung (max. 140 Zeichen), die im Ergebnis angezeigt wird.
Parallelität: 2 gleichzeitige Anfragen · Rate-Limit: ~45 req/min
Modell: claude-opus-4-7 · $15/M input · $75/M output
Die Ergebnisse werden nach Potential-Level sortiert (HIGH → MED → LOW), innerhalb eines Levels nach Google-Bewertung absteigend. Optional wird nach Entfernung zum eingegebenen Standort sortiert.
Nach Abschluss werden angezeigt: Trefferanzahl, Anzahl der Suchanfragen, verbrauchte Tokens und geschätzte Kosten in USD.
Job-System
Die Suche läuft als fire-and-forget Hintergrundjob. Nach dem Start gibt die API sofort eine jobId zurück. Die UI pollt alle 1,5 Sekunden GET /api/search?jobId=… und zeigt den Fortschritt in Echtzeit an. Jobs werden in einer JSON-Datei auf dem Server gespeichert (max. 100 Jobs, älteste werden verdrängt). Ein Server-Neustart während einer laufenden Suche markiert den Job als interrupted.