# Project: EventRate

## Purpose

Maximize Airbnb hosting revenue by automatically detecting high-demand dates in Toronto and adjusting nightly pricing accordingly.

## Problem

Toronto hosts major events (Raptors, Leafs, Blue Jays, concerts, festivals) that drive short-term rental demand. Manually tracking these events and updating Airbnb prices is tedious and error-prone. Missing a single large event can mean hundreds of dollars in lost revenue.

## Solution

A local Python application that:

1. **Fetches** upcoming Toronto events from free public APIs (Ticketmaster, SeatGeek).
2. **Normalizes** events into a common model and deduplicates across sources.
3. **Scores** events based on likely pricing impact (venue size, event type).
4. **Alerts** the host via Telegram with a summary of flagged dates.
5. **Optionally automates** Airbnb calendar price updates using Playwright.

## Scope

### In scope (v1)

- Ticketmaster Discovery API integration
- SeatGeek API integration
- Event normalization and deduplication
- Simple rule-based impact scoring
- Telegram notifications (primary output)
- Playwright-based Airbnb calendar automation (opt-in, fragile)
- CLI with dry-run / alerts-only / full modes
- Docker support

### Out of scope (v1)

- Web UI
- Cloud deployment / hosted service
- Database / persistent storage
- Paid API integrations
- Sophisticated pricing algorithms (ML, dynamic pricing)
- Multi-city support
- Multi-listing support

## Technical constraints

- Python 3.11+
- Runs locally first, cron later
- Configuration via environment variables
- Minimal external dependencies
- Structured logging
- Idempotent where possible

## Key risks and assumptions

| # | Item | Type | Notes |
|---|---|---|---|
| 1 | Airbnb has no public pricing API | Assumption | Must use browser automation; inherently fragile |
| 2 | Airbnb UI selectors will change | Risk | Selectors isolated behind a dedicated module; manual fallback is Telegram-only |
| 3 | Free API tiers have rate limits | Risk | Weekly/monthly runs stay well within limits |
| 4 | Ticketmaster/SeatGeek cover major Toronto events | Assumption | May need additional providers later |
| 5 | 2FA/CAPTCHA on Airbnb login | Risk | Handled by one-time manual login with saved storage state |
| 6 | Event data quality varies across providers | Assumption | Deduplication is best-effort by date + venue + fuzzy name |