wohnbot/README.md

wohn-bot

A Python bot that monitors Berlin's public housing portal (inberlinwohnen.de) and WG rooms (wgcompany.de). Sends Telegram notifications when new listings appear and can automatically apply to some listings.

What it does

• Monitors inberlinwohnen.de for new apartment listings from 6 housing companies (HOWOGE, Gewobag, Degewo, Gesobau, Stadt und Land, WBM)
• Monitors wgcompany.de for WG room listings with configurable filters
• Sends Telegram notifications with listing details
• Logs listing times to CSV for pattern analysis
• Auto-apply feature for supported housing companies

Auto-Apply Support

All six housing companies monitored by this bot now support the autopilot (automatic application) feature. Use autopilot with care — automatic form submission is destructive and may send many requests if configured incorrectly.

Company	Status	Notes
HOWOGE	Working	Fully automated and tested
Degewo	Working	Uses Wohnungshelden portal; automated
Stadt und Land	Working	Embedded form handled automatically
Gewobag	Working	Wohnungshelden iframe handled automatically
Gesobau	Working	Automated form submission implemented
WBM	Working	Automated form submission implemented
WGcompany	Monitoring only	WGcompany monitoring only (no autopilot)

Recommended precautions:

• Run with /autopilot off while testing new selectors or after changing config.
• Inspect data/applications.json and saved screenshots in data/ after enabling autopilot.
• Respect site terms of use and rate limits; set CHECK_INTERVAL appropriately.

Setup

Docker (recommended)

cp .env.example .env
# Edit .env with your credentials
docker compose up -d

Local development

pip install -r requirements.txt
playwright install chromium

export TELEGRAM_BOT_TOKEN=your_token
export TELEGRAM_CHAT_ID=your_chat_id
# ... other env vars

python monitor.py

Configuration

Required environment variables

• TELEGRAM_BOT_TOKEN - Bot token from @BotFather
• TELEGRAM_CHAT_ID - Your Telegram chat ID

InBerlin login (required for auto-apply)

• INBERLIN_EMAIL - Your inberlinwohnen.de email
• INBERLIN_PASSWORD - Your inberlinwohnen.de password

Form data (for auto-apply)

• FORM_ANREDE - Salutation (Herr/Frau)
• FORM_VORNAME - First name
• FORM_NACHNAME - Last name
• FORM_EMAIL - Email address
• FORM_PHONE - Phone number
• FORM_STRASSE - Street name
• FORM_HAUSNUMMER - House number
• FORM_PLZ - Postal code
• FORM_ORT - City
• FORM_PERSONS - Number of persons in household
• FORM_CHILDREN - Number of children
• FORM_INCOME - Monthly net income

WGcompany filters

• WGCOMPANY_ENABLED - Enable WGcompany monitoring (true/false)
• WGCOMPANY_MIN_SIZE - Minimum room size in sqm
• WGCOMPANY_MAX_SIZE - Maximum room size in sqm
• WGCOMPANY_MIN_PRICE - Minimum price in EUR
• WGCOMPANY_MAX_PRICE - Maximum price in EUR
• WGCOMPANY_BEZIRK - District filter (optional)

Telegram Commands

• /autopilot on|off - Enable or disable automatic applications (use /autopilot on or /autopilot off).
• /status - Show current status and statistics (autopilot state, application counts by company).
• /plot - Generate and send a weekly listing-patterns plot (data/weekly_plot.png).
• /errorrate - Generate and send an autopilot success vs failure plot (data/error_rate.png).
• /help - Show available commands and usage information.

Note: The bot only processes commands from the configured TELEGRAM_CHAT_ID. Use /autopilot off while testing selector changes or after modifying configuration to avoid accidental submissions.

Data files

All data is stored in the data/ directory:

• listings.json - Previously seen inberlinwohnen listings
• wgcompany_listings.json - Previously seen WGcompany listings
• applications.json - Application history
• listing_times.csv - Time series data for listings
• state.json - Runtime state (autopilot toggle)
• monitor.log - Application logs

Debugging

When applications fail, the bot saves:

• Screenshots to data/*.png
• Page HTML to data/debug_page.html

Check these files to understand why an application failed.

Code Structure

The bot has been modularized for better maintainability. The main components are:

• main.py: The entry point for the bot.
• handlers/: Contains company-specific handlers for auto-apply functionality. Each company has its own handler file:
  • howoge_handler.py
  • gewobag_handler.py
  • degewo_handler.py
  • gesobau_handler.py
  • stadtundland_handler.py
  • wbm_handler.py
• application_handler.py: Orchestrates the application process by delegating to the appropriate handler.
• telegram_bot.py: Handles Telegram bot commands and notifications.

The handlers/ directory includes a BaseHandler class that provides shared functionality for all company-specific handlers.

Unit Tests

The project includes unit tests to ensure functionality and reliability. Key test files:

• tests/test_telegram_bot.py: Tests the Telegram bot's commands and messaging functionality.
• tests/test_error_rate_plot.py: Tests the error rate plot generator for autopilot applications.

Running Tests

To run the tests, use:

pytest tests/

Ensure all dependencies are installed and the environment is configured correctly before running the tests.

Workflow Diagram

graph TD
    A[Start] --> B[Fetch Listings]
    B --> C{New Listings?}
    C -->|Yes| D[Log to CSV]
    C -->|Yes| E[Send Telegram Notification]
    C -->|Yes| F{Autopilot Enabled?}
    F -->|Yes| G[Auto-Apply to Listings]
    F -->|No| H[Save to Applications.json]
    C -->|No| I[End]
    D --> I
    E --> I
    G --> H
    H --> I

This diagram illustrates the workflow of the bot, from fetching listings to logging, notifying, and optionally applying to new listings.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) License.

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
• NonCommercial — You may not use the material for commercial purposes.

For more details, see the full license text.