名称： seats-aero
描述： 通过 seats.aero API 搜索奖励航班。触发场景：奖励航班查询、里程票预订、积分兑换、商务舱/头等舱余票查找、航线余票搜索。

Seats.aero 奖励航班搜索

通过 seats.aero 合作伙伴 API，搜索 24 个里程计划的奖励航班余票。

设置

开始搜索前，您需要一个 seats.aero API 密钥：

1. 如果用户未提供 API 密钥，请提示：
   - “请提供您的 seats.aero API 密钥。您可以在 https://seats.aero/partner 获取。”
2. 将密钥存储在对话上下文中，供后续请求使用
3. 所有请求需包含请求头：Partner-Authorization: Bearer {api_key}

核心功能

1. 搜索航线 (/search)

针对特定出发地-目的地组合，在所有里程计划中搜索缓存的余票信息。

2. 批量余票查询 (/availability)

探索单个里程计划的所有余票信息，可按区域筛选。

3. 航线发现 (/routes)

获取特定里程计划监控的所有航线。

4. 行程详情 (/trips/{id})

获取特定余票的详细航班航段和预订链接。

快速参考

舱位代码

• Y = 经济舱
• W = 超级经济舱
• J = 商务舱
• F = 头等舱

区域

北美、南美、欧洲、非洲、中东、亚洲、大洋洲

支持的里程计划

aeroplan, alaska, american, aeromexico, azul, copa, delta, emirates,
ethiopian, etihad, finnair, flyingblue, gol, jetblue, lufthansa,
qantas, qatar, sas, saudia, singapore, turkish, united,
virginatlantic, virginaustralia

常见工作流程

查找特定航线的余票

用户：“查找下个月从旧金山到东京的商务舱余票”

1. 使用 /search 端点，参数如下：
   - origin_airport=SFO
   - destination_airport=NRT,HND（东京的两个机场）
   - cabin=J
   - start_date 和 end_date 设置日期范围

探索某里程计划的余票

用户：“从欧洲出发的美联航奖励票有哪些？”

1. 使用 /availability 端点，参数如下：
   - source=united
   - origin_region=Europe

获取预订详情

用户：“给我看看那个航班的详细信息”

1. 使用 /trips/{id}，其中 {id} 为先前搜索得到的余票 ID
2. 响应包含航班航段、时间及预订链接

查看某里程计划监控的航线

用户：“Aeroplan 监控哪些航线？”

1. 使用 /routes 端点，参数为 source=aeroplan

API 参数速查

/search

/availability

脚本使用

对于复杂或重复的搜索，可使用 Python 辅助脚本：

from scripts.seats_api import search_availability, format_results

results = search_availability(
    api_key="your_key",
    origin="SFO",
    destination="NRT",
    start_date="2024-03-01",
    end_date="2024-03-31",
    cabins="J,F"
)
print(format_results(results["data"], cabin="J"))

完整 API 客户端实现请见 scripts/seats_api.py。

响应处理

余票对象字段

• ID - 用于 /trips/{id} 查询
• Route - 出发地-目的地对
• Date - 航班日期
• YAvailable, WAvailable, JAvailable, FAvailable - 布尔值，表示该舱位是否有余票
• YMileageCost 等 - 各舱位所需里程/积分
• YDirects 等 - 可用的直飞航班数量
• Source - 里程计划名称
• ComputedLastSeen - 数据新鲜度时间戳

错误处理

• 401：API 密钥无效或缺失
• 429：请求频率受限，请等待后重试
• 404：无结果或余票 ID 无效

提示

1. 日期范围：保持 30-60 天以获得更快结果
2. 多舱位搜索：同时搜索 J,F 以查找高级舱位选项
3. 直飞航班：使用 only_direct=true 筛选中转航班
4. 分页：使用响应中的 cursor 获取更多结果
5. 数据新鲜度：检查 ComputedLastSeen – 较旧的数据可能已失效

参考文档

完整的 API 规范，包括所有字段和响应模式，请参阅 references/api-spec.md。