google-flights

在 Google 航班上搜索价格、可用性和优惠。当用户询问航班价格、搜索航班、比较机票、查找最便宜的旅行日期或监控常规航线的价格时使用。支持灵活的日期搜索、过滤器（不间断、价格上限、出发/到达时间）、连接质量评分以及带警报的价格跟踪。

## 概述（中文）

在 Google 航班上搜索价格、可用性和优惠。当用户询问航班价格、搜索航班、比较机票、查找最便宜的旅行日期或监控常规航线的价格时使用。支持灵活的日期搜索、过滤器（不间断、价格上限、出发/到达时间）、连接质量评分以及带警报的价格跟踪。

## 原文

# 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