student-rooms

# student-rooms CLI Multi-provider student accommodation finder and monitor. Query Yugo and Aparto for room availability, filter by semester and price, and get alerts when new options appear. ## Setup ```bash cd /path/to/student-rooms-cli source .venv/bin/activate ``` Config file: `config.yaml` (copy from `config.sample.yaml` if missing). Key settings: ```yaml target: country: "Ireland" city: "Dublin" academic_year: start_year: 2026 end_year: 2027 filters: max_weekly_price: 350.0 notifications: type: "openclaw" # or stdout | webhook | telegram openclaw: mode: "message" channel: "telegram" target: "CHAT_ID" ``` ## Commands All commands support `--provider yugo|aparto|all` (default: `all`) and `--json` for structured output. ### discover — List properties ```bash python -m student_rooms discover --provider all python -m student_rooms discover --provider all --json python -m student_rooms discover --city Barcelona --provider aparto --json ``` Returns property names, slugs, locations, and URLs for the target city. ### scan — One-shot availability check ```bash # Semester 1 rooms (default filter) python -m student_rooms scan --provider all --json # All options (full year, semester 2, etc.) python -m student_rooms scan --all-options --json # Scan + send notification for top match python -m student_rooms scan --provider all --notify ``` JSON output structure: ```json { "matchCount": 5, "matches": [ { "provider": "yugo", "property": "Residence Name", "roomType": "Gold Ensuite", "priceWeekly": 310.0, "priceLabel": "€310/week", "available": true, "bookingUrl": "https://...", "startDate": "2026-09-01", "endDate": "2027-01-31", "optionName": "Semester 1", "dedupKey": "yugo|slug|gold ensuite|2026-27|Semester 1" } ] } ``` ### watch — Continuous monitoring ```bash python -m student_rooms watch --provider all ``` Scans at configured interval (default 1h + random jitter). Alerts only on **new** options not previously seen. Persists seen options locally to avoid duplicate alerts. ### probe-booking — Deep booking-flow probe ```bash python -m student_rooms probe-booking --provider yugo --residence "Dominick Place" --json python -m student_rooms probe-booking --provider aparto --residence "Binary Hub" --json ``` Returns booking context, available beds, direct booking links, and portal redirect URLs. Supports `--residence`, `--room`, `--tenancy`, `--index` filters. ### notify — Test notification ```bash python -m student_rooms notify --message "Test alert 🏠" ``` ### test-match — Test semester matching logic ```bash python -m student_rooms test-match --from-year 2026 --to-year 2027 --name "Semester 1" --start-date 2026-09-01 --end-date 2027-01-31 --json ``` ## Location override Override config target with CLI flags: ```bash python -m student_rooms scan --city Barcelona --country Spain --provider all --json ``` ## Agent usage tips - Always use `--json` for structured output. - Use `scan --json` to check current availability; parse `matchCount` and `matches` array. - Use `discover --json` to list what properties exist before scanning. - Use `watch` as a background process for ongoing monitoring. - Combine `scan --notify` to trigger alerts in a single command. - The `dedupKey` field in scan output uniquely identifies each option for tracking. ## OpenClaw integration Set `notifications.type: "openclaw"` in config. Supports two modes: - **message**: Sends alert text via `openclaw message send` to a channel/target. - **agent**: Triggers an OpenClaw agent session with the alert as context. Optional: `create_job_on_match: true` creates a one-shot cron job for reservation assistance. The tool works fully standalone — OpenClaw is only needed if you want the `openclaw` notification backend. ## Notification backends | Backend | Config key | Requires | |---------|-----------|----------| | `stdout` | (default) | Nothing | | `webhook` | `notifications.webhook.url` | Any HTTP endpoint (Discord, Slack, ntfy.sh) | | `telegram` | `notifications.telegram.bot_token` + `chat_id` | Telegram bot | | `openclaw` | `notifications.openclaw.target` | OpenClaw CLI installed | ## Provider notes - **Yugo**: Dynamic API discovery (countries → cities → residences → rooms → tenancy options). Supports full booking-flow probing. - **Aparto**: Scrapes apartostudent.com for property discovery, then probes StarRez portal termIDs. IE/ES/IT share one portal; UK has a separate portal; France has no StarRez portal (discover-only).