Google Flights 搜索

通过 SearchAPI.io 获取 Google Flights 的实时航班数据，然后使用 flight-scoring 技能对结果进行评分与排序，最后**必须**通过 flight-price-monitor 技能保存该次搜索，以启用自动价格追踪。

安装

clawhub install google-flights-search

依赖要求

• Python 3 — 仅使用标准库（urllib、json、argparse），无需 pip 安装任何第三方包。
• SearchAPI.io 账户 — 免费套餐包含每月 100 次请求。[点击此处注册](https://www.searchapi.io/)。
• SEARCHAPI_KEY — 注册 SearchAPI.io 后获取您的 API 密钥，并将其添加至项目根目录下的 .env 文件中。OpenClaw 将自动加载该密钥。

快速参考

使用方法

# 单程搜索
python {baseDir}/scripts/search_searchapi.py 
  --from TLV --to LON --date 2026-03-15 --days 3 --currency USD

# 往返搜索（含前 5 条出发航班的返程详情，往返行程推荐此方式）
python {baseDir}/scripts/search_searchapi.py 
  --from TLV --to BKK --date 2026-03-28 --return-date 2026-04-14 --top 5

全部参数说明

目的地代码说明

Google Flights 支持以下两类代码：

• 机场代码：LHR、CDG、TLV
• 城市代码：LON（涵盖所有伦敦机场）、PAR（涵盖所有巴黎机场）、NYC

当用户未明确指定偏好机场时，请优先使用城市代码。

输出格式

脚本将 JSON 格式结果打印至 stdout。

单程 / 仅出发航班

{
  "origin": "TLV",
  "destination": "LON",
  "flight_type": "one_way",
  "date_range": { "from": "2026-03-15", "to": "2026-03-17", "days_searched": 3 },
  "currency": "USD",
  "total_results": 24,
  "showing": 15,
  "flights": [
    {
      "search_date": "2026-03-15",
      "airline": "El Al",
      "flight_number": "LY315",
      "origin": "TLV",
      "destination": "LHR",
      "departure_time": "22:00",
      "departure_date": "2026-03-15",
      "arrival_time": "01:30",
      "arrival_date": "2026-03-16",
      "duration_minutes": 270,
      "stops": 0,
      "layovers": [],
      "min_layover_minutes": null,
      "price": 1850,
      "overnight": true,
      "booking_token": "WyJDa..."
    }
  ]
}

往返行程（使用 --top 5，含返程航班详情）

当 --top N 与 --return-date 同时使用时，前 N 条出发航班中的每一条均会嵌套一个完整的 return_flight 对象，包含返程航段全部信息：

{
  "origin": "TLV",
  "destination": "BKK",
  "flight_type": "round_trip",
  "return_date": "2026-04-14",
  "return_flights_fetched_for_top": 5,
  "flights": [
    {
      "search_date": "2026-03-28",
      "airline": "Etihad",
      "flight_number": "EY 610",
      "origin": "TLV",
      "destination": "BKK",
      "departure_time": "07:20",
      "departure_date": "2026-03-28",
      "arrival_time": "23:25",
      "arrival_date": "2026-03-28",
      "duration_minutes": 725,
      "stops": 1,
      "layovers": [{"airport": "Zayed International Airport", "duration_minutes": 185}],
      "min_layover_minutes": 185,
      "price": 1569,
      "overnight": false,
      "return_flight": {
        "airline": "Etihad",
        "flight_number": "EY 401",
        "origin": "BKK",
        "destination": "TLV",
        "departure_time": "01:05",
        "departure_date": "2026-04-14",
        "arrival_time": "08:15",
        "arrival_date": "2026-04-14",
        "duration_minutes": 670,
        "stops": 1,
        "layovers": [{"airport": "Zayed International Airport", "duration_minutes": 150}],
        "min_layover_minutes": 150,
        "overnight": false,
        "price": 1569,
        "booking_token": "EhkIAh..."
      }
    }
  ]
}

重要说明： price 字段表示往返总票价（即出发与返程两段之和，且在 return_flight 中重复出现）。return_flight 对象拥有独立的航空公司、航班号、起降时间、经停信息及中转次数 —— 在格式化展示结果时，请完整使用这些字段。

预订令牌查询（--booking-token）

完成评分后，可使用每条高分结果中的 booking_token 查询真实的预订链接。

必须传入与原始搜索完全一致的 --from、--to、--date 参数；若为往返行程，则还必须包含 --return-date。

# 单程预订链接查询
python {baseDir}/scripts/search_searchapi.py 
  --from TLV --to LON --date 2026-03-15 
  --booking-token "WyJDa..."

# 往返预订链接查询 — 必须包含 --return-date
python {baseDir}/scripts/search_searchapi.py 
  --from TLV --to SGN --date 2026-03-29 --return-date 2026-04-14 
  --booking-token "WyJDa..."

返回示例：

{
  "mode": "booking_lookup",
  "total_options": 3,
  "booking_options": [
    {
      "book_with": "El Al",
      "price": 1850,
      "url": "https://www.elal.com/..."
    },
    {
      "book_with": "Kiwi.com",
      "price": 1820,
      "url": "https://www.kiwi.com/..."
    }
  ]
}

优先选择 book_with 字段与航班所属航空公司一致的选项（即直连航空公司官网链接）。 若无匹配项，则选用第一个选项。若 --booking-token 查询失败或未返回任何结果，请回退至 vendor-booking-link 技能。

完整工作流

1. 用户发起航班查询请求
        ↓
2. 提取：出发地、目的地、日期（们）、乘客数量
        ↓
3. 运行 search_searchapi.py，往返行程务必使用 --top 5：
   → 每条结果均包含出发航班 + 嵌套的 return_flight 详情 + booking_token
        ↓
4. 对每条结果应用 flight-scoring 规则：
   - 计算价格得分（0–50 分）
   - 计算直飞得分（0–30 分）
   - 计算便利性得分（0–20 分）
   - 求和 → 总分
        ↓
5. 添加标签（如“综合最优”、“最便宜”、“直飞”、“夜航”、“非工作日+1”等）
        ↓
6. 为每条高分结果获取预订链接：
   a. 使用 booking_token → 执行 search_searchapi.py --booking-token TOKEN → 获取真实航空公司/OTA 链接
   b. 回退方案：若 booking_token 缺失或查询失败 → 使用 vendor-booking-link 技能
        ↓
7. 使用 flight-results-formatter 格式化结果 → 以表格形式呈现每种方案的往返双航段
        ↓
8. 向用户展示格式化后的表格
        ↓
9. 运行 save_monitor.py → 保存本次搜索用于价格监控（强制要求）

展示前必须完成评分。 禁止向用户直接输出原始 JSON。
必须包含预订链接。 优先使用 booking_token 获取真实 URL；若不可用，则回退至 vendor-booking-link。禁止链接至 Google Flights 或聚合平台。
往返行程必须使用 --top 5 以获取返程航班详情；若不带 --top，仅返回出发航班信息。

第 8 步：保存价格监控（强制要求）

向用户展示结果后，**必须**保存本次搜索以启用价格监控。请从排名前 10–15 的航班中构建紧凑快照，格式为 "Airline|FlightNum|DepTime": price 键值对，然后执行：

python3 {baseDir}/../flight-price-monitor/scripts/save_monitor.py 
  --user-id "" 
  --from  --to  --date  
  --return-date  
  --currency  --adults  
  --channel  --delivery-to "" 
  --flights ''

• --user-id：来自会话的 peer ID（例如 whatsapp:+972523866782）；若未知，可用用户姓名代替。
• --channel：用户当前所在渠道（whatsapp、telegram 等）。
• --delivery-to：用户在该渠道上的地址；若未知，可设为 last。
• --flights：由结果中提取的 "Airline|FlightNum|HH:MM": price 键值对组成的 JSON 对象。
• 单程搜索请勿传入 --return-date 参数。

该操作将覆盖该用户此前已存在的监控任务。后台 cron 任务每 2 小时检查一次价格变动，并向用户推送通知。

脚本输出字段 → 评分输入字段映射

错误处理

备注

• El Al 不在安息日（Shabbat）执飞：从 TLV 出发的周五晚间及周六航班，El Al 不提供服务，因此不会出现在结果中。
• 次要机场：Wizz Air 和 Ryanair 常使用 LTN、STN、BGY 等机场代码 —— 当脚本返回这些机场的结果时，请主动向用户说明具体机场名称。
• 价格单位：默认为每人单价，除非设置了 --adults；对于多人出行，请按人数相乘并注明总价。
• 往返行程：务必使用 --return-date YYYY-MM-DD --top 5 进行搜索，以同时获取往返双航段详情。