Doctor Collector

Doctor Collector is a local Python app for finding therapist contact details on therapie.de, reviewing the collected results, and optionally sending an initial consultation request by email.

Use the localhost web UI for guided setup, progress, CSV/table review, and optional sending, or use the same collect-first, contact-second workflow from the command line.

Quick Start

1. Install Python

Download and install Python 3.11 or newer from the official website:

Download Python

During installation on Windows, make sure to check "Add Python to PATH".

2. Download this project

Download as ZIP and extract it, or use Git:

git clone https://github.com/kequach/Doctor-collector.git

3. Install dependencies

Open a terminal in the project folder and run:

pip install -e .

4. Configure

Either use the web UI in the next step, or open config.yaml in any text editor and fill in:

• Your postal code and desired search radius
• Your email credentials (only needed if you want to send emails — see Contact settings below)

5. Run with the web UI

Start the local web UI:

python -m doctor_collector --web

Then open http://127.0.0.1:8000/ in your browser. From there you can edit the config.yaml settings with form fields, collect therapists, review the table, and send emails to the collected addresses after confirming the CSV review.

Or run from the terminal

python -m doctor_collector --collect

This searches therapie.de, filters the results, and saves everything to therapists.csv. You can open this file in Excel.

Usage

Command	What it does
python -m doctor_collector --web	Open the localhost web UI
python -m doctor_collector --collect	Find therapists and save to therapists.csv
python -m doctor_collector --contact	Send emails to reviewed therapists in therapists.csv

A typical terminal workflow:

1. Run with --collect first to review the results in therapists.csv
2. Once you're happy with the list, run with --contact to send emails
3. The tool remembers who you already contacted — running again only emails new therapists

The combined --collect --contact shortcut is intentionally blocked so you always have a chance to review the CSV before emails go out.

Web UI

The web UI runs only on your computer. No collected data or email credentials are uploaded. Use it to enter your search settings, collect therapists, review the table, copy email addresses, and optionally send emails.

Step-by-step guide

1. Start the web UI:

   python -m doctor_collector --web

2. Open http://127.0.0.1:8000/ in your browser.

3. Enter your postal code, search radius, and therapy preferences.

4. Adjust the exclusion words if you want to skip certain types of therapists.

5. If you want Doctor Collector to send emails for you, fill in the email message and mail account settings. Otherwise, leave them empty and use the copy button after reviewing the list.

6. Click Konfiguration speichern if you want to keep these settings for next time.

7. Click Sammeln to start collecting therapists. Leave the page open while it runs.

8. Review the table when collection finishes. Use Aktiv to include or skip a row, and Entfernen to remove a row from the list.

9. Copy the active email addresses if you want to send messages yourself.

10. To send from the app, check CSV geprüft after reviewing the table, then click E-Mails senden.

The collected list is also saved as therapists.csv in the project folder. Doctor Collector remembers which email addresses it has already contacted, so later sending runs skip them.

To use a different config file or port:

python -m doctor_collector --web --config path/to/config.yaml --port 8080

Configuration

All settings are in config.yaml. Open it in any text editor.

Search settings

therapie:
  post_code: "10115"         # your postal code
  search_radius_km: 25       # search radius: 10, 25, 50, or 100 km
  work_focus: ""             # optional: Worum geht es? / URL parameter arbeitsschwerpunkt
  therapy_form: 1            # Für wen? / URL parameter therapieangebot
  therapy_type: 2            # 1 = Analytische, 2 = Verhaltenstherapie, 3 = Tiefenpsychologisch, 4 = Systemische
  billing_method: ""         # optional: Abrechnung / URL parameter abrechnungsverfahren
  availability: ""           # optional: Freie Plätze / URL parameter terminzeitraum
  free_text: ""              # optional: Freitextsuche / URL parameter weiteres
  start_page: 1              # first search-result page to read
  max_pages: 100             # how many pages of results to go through
  max_therapists: 0          # maximum profiles to gather; 0 means no limit
  request_delay_seconds: 1.5 # at least 0.1 seconds between request starts

search_radius_km must be 10, 25, 50, or 100. max_therapists: 0 means no limit. request_delay_seconds controls pacing between HTTP request starts; increase it if therapie.de returns repeated 429 or 403 responses. Repeated collection runs reuse matching rows already present in therapists.csv when the same profile URL appears again.

For work_focus, billing_method, availability, and therapy_form, the web UI shows therapie.de's human-readable labels and saves the matching URL values. Leave optional fields empty to omit those filters.

Filters

filters:
  exclude_types:
    - "Heil"       # excludes Heilpraktiker
    - "Kinder"     # excludes child/youth therapists
    - "Privat"     # excludes private-only therapists

Add or remove keywords to control which therapists are excluded. Only therapists with an email address are included.

Contact settings

Only needed for --contact or web UI email sending. Gmail, Outlook, Yahoo, and many other providers require app passwords instead of your normal account password.

contact:
  subject: "Erstgespräch Anfrage"
  body: |
    Sehr geehrte Damen und Herren,

    Ich möchte ein Erstgespräch bei Ihnen anfragen.
    ...

  smtp_host: "smtp.gmail.com"
  smtp_port: 465
  use_tls: true
  smtp_user: "you@gmail.com"
  smtp_password: "your-16-char-app-password"
  from_address: "you@gmail.com"

Environment overrides are available for Docker and terminal runs: CSV_FILE, STATE_FILE, THERAPIE_POST_CODE, THERAPIE_SEARCH_RADIUS_KM, THERAPIE_WORK_FOCUS, THERAPIE_THERAPY_FORM, THERAPIE_THERAPY_TYPE, THERAPIE_BILLING_METHOD, THERAPIE_AVAILABILITY, THERAPIE_FREE_TEXT, THERAPIE_START_PAGE, THERAPIE_MAX_PAGES, THERAPIE_MAX_THERAPISTS, THERAPIE_REQUEST_DELAY, FILTER_EXCLUDE_TYPES, CONTACT_SUBJECT, CONTACT_BODY, CONTACT_SMTP_HOST, CONTACT_SMTP_PORT, CONTACT_USE_TLS, CONTACT_SMTP_USER, CONTACT_SMTP_PASSWORD, and CONTACT_FROM_ADDRESS.

Docker

All examples below mount a ./data folder so output files are saved on your machine.

Collect:

docker run --rm -v ./data:/app/data \
  -e CSV_FILE=/app/data/therapists.csv \
  -e THERAPIE_POST_CODE=10115 \
  -e THERAPIE_SEARCH_RADIUS_KM=25 \
  kequach/doctor-collector python -m doctor_collector --collect

Review ./data/therapists.csv, then contact:

docker run --rm -v ./data:/app/data \
  -e CSV_FILE=/app/data/therapists.csv \
  -e STATE_FILE=/app/data/.contacted_therapists.json \
  -e CONTACT_SMTP_USER=you@gmail.com \
  -e CONTACT_SMTP_PASSWORD=your-16-char-app-password \
  -e CONTACT_FROM_ADDRESS=you@gmail.com \
  kequach/doctor-collector python -m doctor_collector --contact

You can also use the included docker-compose.yml, which defaults to collection:

docker compose run --rm doctor-collector
docker compose run --rm doctor-collector python -m doctor_collector --contact

Do not combine collect and contact in one Docker command.

Development

Install development dependencies with:

pip install -e ".[dev]"

Before finishing code changes, run:

python -m ruff check src/ tests/
python -m pytest tests/ --tb=short

Codex workflow docs live in docs/CODEX_WORKFLOW.md, with copy/paste feature request prompts in docs/CODEX_FEATURE_REQUEST_TEMPLATE.md.

License

MIT