Murray
30ee5fbd85
- Python flight price monitor for BER↔EZE and other routes - Adapter pattern for extensibility (Kiwi/Tequila implemented) - OpenClaw alerting integration - Cron-friendly one-shot execution - Full logging of all checks - Graceful handling when API key not set Implements monkey-island/flight-monitor#2
206 lines
4.4 KiB
Markdown
206 lines
4.4 KiB
Markdown
# Flight Price Monitor
|
|
|
|
Daily flight price monitor that checks configured routes and alerts when prices drop below threshold.
|
|
|
|
## Features
|
|
|
|
- ✈️ Monitor multiple flight routes (BER→EZE, etc.)
|
|
- 🔔 OpenClaw alerts when prices drop below threshold
|
|
- 📊 Extensible adapter pattern for multiple price sources
|
|
- 📝 Full logging of all checks (hits and misses)
|
|
- 🔧 Cron-friendly one-shot execution
|
|
|
|
## Setup
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Get a Kiwi API Key
|
|
|
|
1. Sign up at https://tequila.kiwi.com/portal/login
|
|
2. Create an API key
|
|
3. Set environment variable:
|
|
|
|
```bash
|
|
export KIWI_API_KEY="your-api-key-here"
|
|
```
|
|
|
|
Or create a `.env` file:
|
|
|
|
```bash
|
|
KIWI_API_KEY=your-api-key-here
|
|
```
|
|
|
|
### 3. Configure Routes
|
|
|
|
Edit `config.json`:
|
|
|
|
```json
|
|
{
|
|
"routes": [
|
|
{
|
|
"origin": "BER",
|
|
"destination": "EZE",
|
|
"trip_type": "round_trip",
|
|
"threshold_eur": 700,
|
|
"duration_weeks": [2, 3, 4],
|
|
"preferred_months": [12, 1, 2, 3],
|
|
"monitor_year_round": true
|
|
}
|
|
],
|
|
"check_interval": "daily"
|
|
}
|
|
```
|
|
|
|
**Config Fields:**
|
|
|
|
- `origin`, `destination`: IATA airport codes
|
|
- `threshold_eur`: Alert if price drops below this (in EUR)
|
|
- `duration_weeks`: Trip lengths to search (in weeks)
|
|
- `preferred_months`: Months to prioritize (1-12)
|
|
- `monitor_year_round`: `true` to search all months, `false` to only search `preferred_months`
|
|
|
|
You can add multiple routes — the monitor will check them all.
|
|
|
|
### 4. Run
|
|
|
|
```bash
|
|
python monitor.py
|
|
```
|
|
|
|
Logs are written to `monitor.log` and stdout.
|
|
|
|
## Scheduling (Cron)
|
|
|
|
To run daily at 6 AM:
|
|
|
|
```bash
|
|
crontab -e
|
|
```
|
|
|
|
Add:
|
|
|
|
```
|
|
0 6 * * * cd /path/to/flight-monitor && /usr/bin/python3 monitor.py
|
|
```
|
|
|
|
Or use OpenClaw cron (recommended):
|
|
|
|
```bash
|
|
openclaw cron add \
|
|
--schedule '0 6 * * *' \
|
|
--command 'cd /path/to/flight-monitor && python monitor.py' \
|
|
--name 'Flight Price Monitor'
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Adapter Pattern
|
|
|
|
The monitor uses an adapter pattern to support multiple price sources:
|
|
|
|
```
|
|
adapters/
|
|
base.py # Abstract FlightAdapter interface
|
|
kiwi.py # Kiwi/Tequila API implementation
|
|
```
|
|
|
|
Each adapter implements:
|
|
|
|
- `search_round_trip()` — returns normalized results
|
|
- `get_name()` — adapter name
|
|
|
|
All results follow this schema:
|
|
|
|
```python
|
|
{
|
|
"price_eur": float,
|
|
"airline": str,
|
|
"departure": datetime,
|
|
"return": datetime,
|
|
"link": str, # Booking URL
|
|
"source": str # Adapter name
|
|
}
|
|
```
|
|
|
|
### Adding a New Adapter
|
|
|
|
1. Create `adapters/my_adapter.py`:
|
|
|
|
```python
|
|
from adapters.base import FlightAdapter
|
|
|
|
class MyAdapter(FlightAdapter):
|
|
def get_name(self) -> str:
|
|
return "MySource"
|
|
|
|
def search_round_trip(self, origin, destination, departure_date, return_date, **kwargs):
|
|
# Your implementation here
|
|
# Must return list of normalized results (see schema above)
|
|
pass
|
|
```
|
|
|
|
2. Register in `adapters/__init__.py`:
|
|
|
|
```python
|
|
from adapters.my_adapter import MyAdapter
|
|
__all__ = [..., "MyAdapter"]
|
|
```
|
|
|
|
3. Update `monitor.py` to use your adapter:
|
|
|
|
```python
|
|
adapter = MyAdapter()
|
|
```
|
|
|
|
You can also make the adapter configurable via `config.json` if needed.
|
|
|
|
## Alerting
|
|
|
|
When a price drop is detected, the monitor sends an alert via OpenClaw:
|
|
|
|
```bash
|
|
openclaw system event --text "✈️ BER→EZE €650 on 2026-04-15 → 2026-04-29 (Lufthansa) — below €700! https://..." --mode now
|
|
```
|
|
|
|
This routes the alert to your configured OpenClaw channels (Telegram, Discord, Signal, etc.).
|
|
|
|
## Logs
|
|
|
|
All checks are logged to `monitor.log` with timestamps:
|
|
|
|
```
|
|
2026-03-21 18:00:00 [INFO] === Flight Monitor Starting ===
|
|
2026-03-21 18:00:00 [INFO] Checking route BER→EZE (threshold: €700)
|
|
2026-03-21 18:00:01 [INFO] 2026-04-15 → 2026-04-29: €850 (Lufthansa)
|
|
2026-03-21 18:00:02 [INFO] 2026-05-01 → 2026-05-15: €620 (Air France)
|
|
2026-03-21 18:00:02 [INFO] Alert sent via OpenClaw
|
|
2026-03-21 18:00:03 [INFO] === Flight Monitor Complete ===
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**"KIWI_API_KEY environment variable not set"**
|
|
|
|
- Set the `KIWI_API_KEY` env var (see Setup step 2)
|
|
- The monitor will exit gracefully (not crash) if the key is missing
|
|
|
|
**No results returned**
|
|
|
|
- Check `monitor.log` for API errors
|
|
- Verify your IATA codes are correct (e.g., "BER" not "Berlin")
|
|
- Try a broader date range (increase `duration_weeks` or `preferred_months`)
|
|
|
|
**OpenClaw alert not sent**
|
|
|
|
- Verify `openclaw` CLI is in PATH
|
|
- Check OpenClaw is running: `openclaw status`
|
|
- Look for error messages in `monitor.log`
|
|
|
|
## License
|
|
|
|
MIT
|