{"skill":{"slug":"student-rooms","displayName":"student-rooms","summary":"Search, scan, and monitor student accommodation availability across Yugo and Aparto providers. Use when the user asks about student housing, room availabilit...","description":"---\nname: student-rooms\ndescription: Search, scan, and monitor student accommodation availability across Yugo and Aparto providers. Use when the user asks about student housing, room availability, semester accommodation, booking options, or price comparisons in any supported city. Covers Yugo (11 countries, 70+ cities including UK, Ireland, Spain, Germany, France, Italy, Portugal, Austria, Australia, USA, UAE) and Aparto (14 cities across Ireland, Spain, Italy, UK, France). Supports semester filtering, continuous watch mode with alerts, booking-flow probing, and multiple notification backends (stdout, webhook, Telegram, OpenClaw). Works standalone (no OpenClaw required) but has native OpenClaw integration for notifications and agent-mode alerts.\n---\n\n# student-rooms CLI\n\nMulti-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.\n\n## Setup\n\n```bash\ncd /path/to/student-rooms-cli\nsource .venv/bin/activate\n```\n\nConfig file: `config.yaml` (copy from `config.sample.yaml` if missing). Key settings:\n\n```yaml\ntarget:\n  country: \"Ireland\"\n  city: \"Dublin\"\nacademic_year:\n  start_year: 2026\n  end_year: 2027\nfilters:\n  max_weekly_price: 350.0\nnotifications:\n  type: \"openclaw\"  # or stdout | webhook | telegram\n  openclaw:\n    mode: \"message\"\n    channel: \"telegram\"\n    target: \"CHAT_ID\"\n```\n\n## Commands\n\nAll commands support `--provider yugo|aparto|all` (default: `all`) and `--json` for structured output.\n\n### discover — List properties\n\n```bash\npython -m student_rooms discover --provider all\npython -m student_rooms discover --provider all --json\npython -m student_rooms discover --city Barcelona --provider aparto --json\n```\n\nReturns property names, slugs, locations, and URLs for the target city.\n\n### scan — One-shot availability check\n\n```bash\n# Semester 1 rooms (default filter)\npython -m student_rooms scan --provider all --json\n\n# All options (full year, semester 2, etc.)\npython -m student_rooms scan --all-options --json\n\n# Scan + send notification for top match\npython -m student_rooms scan --provider all --notify\n```\n\nJSON output structure:\n```json\n{\n  \"matchCount\": 5,\n  \"matches\": [\n    {\n      \"provider\": \"yugo\",\n      \"property\": \"Residence Name\",\n      \"roomType\": \"Gold Ensuite\",\n      \"priceWeekly\": 310.0,\n      \"priceLabel\": \"€310/week\",\n      \"available\": true,\n      \"bookingUrl\": \"https://...\",\n      \"startDate\": \"2026-09-01\",\n      \"endDate\": \"2027-01-31\",\n      \"optionName\": \"Semester 1\",\n      \"dedupKey\": \"yugo|slug|gold ensuite|2026-27|Semester 1\"\n    }\n  ]\n}\n```\n\n### watch — Continuous monitoring\n\n```bash\npython -m student_rooms watch --provider all\n```\n\nScans at configured interval (default 1h + random jitter). Alerts only on **new** options not previously seen. Persists seen options locally to avoid duplicate alerts.\n\n### probe-booking — Deep booking-flow probe\n\n```bash\npython -m student_rooms probe-booking --provider yugo --residence \"Dominick Place\" --json\npython -m student_rooms probe-booking --provider aparto --residence \"Binary Hub\" --json\n```\n\nReturns booking context, available beds, direct booking links, and portal redirect URLs. Supports `--residence`, `--room`, `--tenancy`, `--index` filters.\n\n### notify — Test notification\n\n```bash\npython -m student_rooms notify --message \"Test alert 🏠\"\n```\n\n### test-match — Test semester matching logic\n\n```bash\npython -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\n```\n\n## Location override\n\nOverride config target with CLI flags:\n\n```bash\npython -m student_rooms scan --city Barcelona --country Spain --provider all --json\n```\n\n## Agent usage tips\n\n- Always use `--json` for structured output.\n- Use `scan --json` to check current availability; parse `matchCount` and `matches` array.\n- Use `discover --json` to list what properties exist before scanning.\n- Use `watch` as a background process for ongoing monitoring.\n- Combine `scan --notify` to trigger alerts in a single command.\n- The `dedupKey` field in scan output uniquely identifies each option for tracking.\n\n## OpenClaw integration\n\nSet `notifications.type: \"openclaw\"` in config. Supports two modes:\n\n- **message**: Sends alert text via `openclaw message send` to a channel/target.\n- **agent**: Triggers an OpenClaw agent session with the alert as context.\n\nOptional: `create_job_on_match: true` creates a one-shot cron job for reservation assistance.\n\nThe tool works fully standalone — OpenClaw is only needed if you want the `openclaw` notification backend.\n\n## Notification backends\n\n| Backend | Config key | Requires |\n|---------|-----------|----------|\n| `stdout` | (default) | Nothing |\n| `webhook` | `notifications.webhook.url` | Any HTTP endpoint (Discord, Slack, ntfy.sh) |\n| `telegram` | `notifications.telegram.bot_token` + `chat_id` | Telegram bot |\n| `openclaw` | `notifications.openclaw.target` | OpenClaw CLI installed |\n\n## Provider notes\n\n- **Yugo**: Dynamic API discovery (countries → cities → residences → rooms → tenancy options). Supports full booking-flow probing.\n- **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).\n","topics":["Webhook","Telegram"],"tags":{"latest":"1.1.0"},"stats":{"comments":0,"downloads":819,"installsAllTime":31,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1772149649876,"updatedAt":1778491652688},"latestVersion":{"version":"1.1.0","createdAt":1772975679699,"changelog":"v1.1.0: centralized semester detection, 80 tests, removed hardcoded paths from SKILL.md, README improvements","license":null},"metadata":null,"owner":{"handle":"gonzalopezgil","userId":"s172ksh0q22wmzpzgmat7ra7e583y3jd","displayName":"Gonzalo López Gil","image":"https://avatars.githubusercontent.com/u/74659017?v=4"},"moderation":null}