google-flights

Search Google Flights for prices, availability, and deals. Use when user asks about flight prices, searching for flights, comparing airfares, finding the cheapest travel dates, or monitoring prices on regular routes. Supports flexible date search, filters (nonstop, price cap, departure/arrival times), connection quality scoring, and price tracking with alerts.

# Google Flights

Flight search with flexible dates, smart filters, connection scoring, and price tracking.

## Quick Start

```bash
cd ~/clawd/skills/google-flights
source .venv/bin/activate

# Basic search
./scripts/search.py LAX JFK tomorrow

# Flexible dates — find cheapest day
./scripts/search.py LAX JFK "apr 15" --flex 3

# Nonstop under $500
./scripts/search.py SFO ORD "next friday" --nonstop --max-price 500

# Watch a route for price drops
./scripts/watch-route.py add LAX JFK --alert-below 350
./scripts/watch-route.py watch
```

## Search

### Basic Usage

```bash
./scripts/search.py <from> <to> <date> [options]
```

### Date Formats

Natural language supported:
- `tomorrow`, `today`
- `next friday`, `next week`
- `mar 15`, `March 15`, `3/15`
- `2026-04-15` (ISO format)

### Filters

| Flag | Short | Description |
|------|-------|-------------|
| `--flex N` | `-f` | Search ±N days around date |
| `--nonstop` | `-n` | Nonstop flights only |
| `--max-price` | `-m` | Maximum price |
| `--depart-after` | | Depart after time (8am, 14:00) |
| `--arrive-before` | | Arrive before time (6pm, 18:00) |
| `--seat` | `-s` | economy, premium-economy, business, first |
| `--adults` | `-a` | Number of adults (default: 1) |
| `--children` | `-c` | Number of children |
| `--return` | `-r` | Return date for round-trip |

### Output

| Flag | Description |
|------|-------------|
| `--top N` | Show top N results (default: 5) |
| `--sort` | Sort by: price (default), score, duration |
| `--show-scores` | Show connection quality breakdown |
| `--json` | JSON output |

### Examples

```bash
# Find cheapest day in a week window
./scripts/search.py LAX JFK "apr 10" --flex 7 --nonstop

# Morning departure, business class
./scripts/search.py SFO LHR "may 1" --seat business --depart-after 8am

# Family trip sorted by connection quality
./scripts/search.py DEN MCO "jun 15" -a 2 -c 2 --sort score --show-scores

# Round-trip under $800
./scripts/search.py SEA LAX "apr 1" --return "apr 8" --max-price 800
```

## Price Tracking

Track specific flights and get alerts on price changes.

```bash
# Track a specific flight
./scripts/track.py add LAX JFK "2026-05-15" --alert-below 400

# Track round-trip
./scripts/track.py add LAX JFK "may 1" --return "may 8" -a 350

# Check all tracked flights
./scripts/track.py check

# View price history
./scripts/track.py history LAX-JFK-2026-05-15

# List / remove
./scripts/track.py list
./scripts/track.py remove LAX-JFK-2026-05-15
```

## Route Watching

Monitor regular routes (e.g., commute between two cities).

```bash
# Add a route to watch
./scripts/watch-route.py add LAX JFK --alert-below 400

# Check all watched routes
./scripts/watch-route.py watch

# List watched routes
./scripts/watch-route.py list

# Remove a route
./scripts/watch-route.py remove LAX-JFK
```

### Cron Integration

Set up daily price checks:

```bash
openclaw cron add \
  --name "Flight Price Watch" \
  --cron "0 9 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "cd ~/clawd/skills/google-flights && source .venv/bin/activate && ./scripts/watch-route.py watch. Alert user only if prices drop below threshold."
```

## Connection Quality Scoring

Flights scored 0-100 based on:

| Factor | Impact |
|--------|--------|
| Nonstop flight | +15 |
| Preferred airline | +10 |
| Tight connection (<45min) | -30 |
| Long layover (>4hr) | -5 to -25 |
| Problematic connection airport | -10 to -20 |
| Winter weather risk (ORD, EWR, etc.) | -15 |
| Red-eye (depart after 10pm) | -15 |
| Early departure (<6am) | -10 |
| Avoided airline | -25 |

Use `--show-scores` to see breakdown or `--sort score` to prioritize quality.

## Configuration

Copy `config.example.json` to `config.json` and customize:

```json
{
  "preferred_airlines": ["United", "Delta"],
  "avoid_airlines": ["Spirit"],
  "prefer_nonstop": true,
  "max_layover_hours": 4,
  "min_layover_minutes": 45,
  "home_airports": ["LAX", "JFK"],
  "loyalty_programs": {
    "united_mileageplus": "gold"
  }
}
```

## Setup

```bash
cd ~/clawd/skills/google-flights
uv venv && source .venv/bin/activate && uv pip install fast-flights
chmod +x scripts/*.py
cp config.example.json config.json  # then edit
```

## Data Files

- `~/clawd/memory/flight-tracking.json` — Tracked flights
- `~/clawd/memory/flight-prices.jsonl` — Price history
- `~/clawd/memory/route-watch-state.json` — Watched routes