student-rooms

Search, scan, and monitor student accommodation availability across Yugo and Aparto providers. Use when the user asks about student housing, room availabilit...

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

cd /path/to/student-rooms-cli
source .venv/bin/activate

Config file: config.yaml (copy from config.sample.yaml if missing). Key settings:

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

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

# 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:

{
  "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

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

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

python -m student_rooms notify --message "Test alert 🏠"

test-match — Test semester matching logic

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:

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).