seats-aero

Seats.aero 技能

搜索 27 个里程计划的缓存和实时奖励航班余位（包括 2026 年 4 月新增的 Spirit Free Spirit 和 Frontier Miles）。查找最便宜的奖励航班、比较各计划，并获取预订链接。

来源： seats.aero | API 文档 | 知识库

身份验证

在 .env 文件中设置 SEATS_AERO_API_KEY。从 Settings > API tab 获取（需要 Pro 账户）。

所有请求都使用 Partner-Authorization 标头。Pro 用户每天可进行 1,000 次 API 调用，用于非商业用途。

API 基础地址

https://seats.aero/partnerapi

核心概念

Saver 价格与动态定价

奖励座位分为两类：

• Saver（固定价格）： 里程费用固定、可预测。通常是唯一可通过合作伙伴计划预订的类型。性价比最高。在 Seats.aero 上始终显示。
• 动态定价： 价格会根据需求变化（类似现金票价）。价格可能合理，也可能极其昂贵。Seats.aero 默认会过滤掉价格过高的动态奖励票。

动态价格过滤阈值

超过以下每小时阈值的奖励票会自动隐藏：

计划	经济舱	高级经济舱	商务舱	头等舱
American	总计 <100K	总计 <100K	总计 <150K	总计 <200K
United	7,500/小时	10,000/小时	14,000/小时	20,000/小时（最多 10 小时）
Delta	10,000/小时	15,000/小时	20,000/小时	不适用
Aeroplan	7,500/小时	10,000/小时	12,500/小时	15,000/小时
Flying Blue	5,000/小时	10,000/小时	15,000/小时	15,000/小时
Alaska	总计 <150K	总计 <150K	总计 <150K	总计 <150K
Aeromexico	10,000/小时（最多 10 小时）	15,000/小时	20,000/小时	不适用
Etihad	10,000/小时（最多 10 小时）	15,000/小时	20,000/小时	不适用
JetBlue	10,000/小时	15,000/小时	20,000/小时	不适用
Qantas	7,500/小时	10,000/小时	20,000/小时	25,000/小时

若要查看所有动态定价结果（包括价格昂贵的结果）：在缓存搜索/批量查询中传入 include_filtered=true，或在实时搜索中传入 disable_filters=true / show_dynamic_pricing=true。

幽灵余位

有时航班显示可预订，但实际上并没有座位。原因包括：

• 缓存/过期结果： 检查 ComputedLastSeen，确认数据是否最新。
• 同步延迟： 座位已被订走，但合作伙伴系统尚未更新。
• 合作伙伴数据源故障： 计划错误地显示合作航司有余位。

转移积分前，务必在航空公司官网核实。 比较同一联盟中的多个计划。如有可能，请致电确认并申请保留座位。

外国计划注意事项

某些计划（Smiles、TudoAzul 等）可能要求提供当地税号、使用当地支付方式，或者只支持当地语言。它们仍会出现在结果中，因为可以作为参考信号：如果 Azul TudoAzul 显示 United 有 Saver 余位，那么通过 Aeroplan 或其他你可以使用的星空联盟合作伙伴计划预订同一余位的可能性也很高。

奖励座位放出日期

各航空公司放出奖励座位的提前时间不同（例如，Aeroplan 最多会提前 358 天放出座位）。请查看 seats.aero/tools/releases，了解各计划中每家航空公司的最远可查询日期。此信息有助于规划何时开始搜索。

余位对象

缓存搜索/批量余位查询的每条结果都是一个摘要，将某条航线、某个日期和某个计划的所有航班归入同一个对象。例如，如果 Alaska 在 3 月 16 日提供 3 个不同的 SFO>LAX 航班，它们都会显示在同一个余位对象中。MileageCost 字段显示最便宜的选项。RemainingSeats 字段显示所有航班中的最大座位数。使用 Get Trips 查看每个航班的详细信息。

里程计划来源

来源	计划	舱位	座位数	行程数据	税费
eurobonus	SAS EuroBonus	Y/J	是	是	是
virginatlantic	Virgin Atlantic Flying Club	Y/W/J	是	是	是
aeromexico	Aeromexico Club Premier	Y/W/J	是	是	是
american	American Airlines AAdvantage	Y/W/J/F	仅在剩余座位较少时提供*	是	是
delta	Delta SkyMiles	Y/W/J	是	是	是
etihad	Etihad Guest	Y/J/F	是	是	是
united	United MileagePlus	Y/W/J/F	是	是	是
emirates	Emirates Skywards	Y/W/J/F	否	部分**	是
aeroplan	Air Canada Aeroplan	Y/W/J/F	通常有***	是	是
alaska	Alaska Mileage Plan	Y/W/J/F	是	是	是
velocity	Virgin Australia Velocity	Y/W/J/F	是	是	是
qantas	Qantas Frequent Flyer	Y/W/J/F	否	是	是
connectmiles	Copa ConnectMiles	Y/J/F	否	是	是
azul	Azul TudoAzul	Y/J	否	是	是
smiles	GOL Smiles	Y/W/J/F	是	是	是
flyingblue	Air France/KLM Flying Blue	Y/W/J/F	是	是	是
jetblue	JetBlue TrueBlue	Y/W/J/F	是	是	是
qatar	Qatar Privilege Club	Y/J/F	否	是	否
turkish	Turkish Miles & Smiles	Y/J	否	是	否
singapore	Singapore KrisFlyer	Y/W/J/F	否	是	否
ethiopian	Ethiopian ShebaMiles	Y/J	是	是	是
saudia	Saudi AlFursan	Y/J/F	是	是	是
finnair	Finnair Plus	Y/W/J/F	是	是	是
lufthansa	Lufthansa Miles&More	Y/J/F	是	是	是
frontier	Frontier Airlines	Y	否	是	是
spirit	Spirit Airlines	Y	是	是	是

* AA 仅在剩余座位较少时提供座位数；否则显示 0。 ** Emirates 的中转航班可能缺少字段。 *** Aeroplan 通常会提供座位数，但极少数情况下可能为 0。

舱位代码： Y = 经济舱，W = 超级经济舱，J = 商务舱，F = 头等舱

缓存搜索（主要端点）

在指定机场和日期范围内，搜索所有计划的奖励机票可用情况。适用于针对特定航线和日期的搜索。

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/search?origin_airport=SFO&destination_airport=NRT&start_date=2026-08-01&end_date=2026-08-31" | jq '.'

参数

参数	必填	说明
origin_airport	是	以逗号分隔的机场代码：SFO,LAX
destination_airport	是	以逗号分隔的机场代码：NRT,HND
start_date	否	YYYY-MM-DD 格式
end_date	否	YYYY-MM-DD 格式
cabins	否	以逗号分隔：economy,business
sources	否	以逗号分隔的计划筛选项：aeroplan,united
only_direct_flights	否	布尔值。仅限直飞航班。
carriers	否	以逗号分隔的航空公司代码：DL,AA
order_by	否	默认：按日期和舱位优先级排序。lowest_mileage 表示优先显示所需里程最少的航班。
include_trips	否	布尔值。在响应中包含航班详情（速度较慢、数据量较大）。
minify_trips	否	布尔值。与 include_trips 配合使用时，每个行程返回较少字段，以提升性能。
include_filtered	否	布尔值。显示已筛除的高价动态奖励机票。
take	否	每页结果数。10-1000，默认值为 500。
skip	否	分页偏移量。
cursor	否	上一响应中的游标，用于保持分页结果一致。

响应字段（Availability 对象）

每条结果汇总一条航线、一个日期和一个计划的所有航班：

字段	描述
ID	Availability ID（与 /trips/{id} 配合使用以获取航班详情）
Route.OriginAirport	出发机场代码
Route.DestinationAirport	到达机场代码
Date	出发日期
Source	里程计划
YAvailable、WAvailable、JAvailable、FAvailable	各舱位是否有空位
YMileageCost、WMileageCost、JMileageCost、FMileageCost	所有航班中的最低积分价格（字符串）
YRemainingSeats、WRemainingSeats、JRemainingSeats、FRemainingSeats	所有航班中的最大剩余座位数
YAirlines、WAirlines、JAirlines、FAirlines	执飞航空公司
YDirect、WDirect、JDirect、FDirect	是否有直飞航班
ComputedLastSeen	上次确认有空位的时间

获取行程详情

从 Availability 对象中获取航班级别的信息。返回包含航段、预订链接和坐标的单个行程。

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/trips/{availability_id}" | jq '.'

参数

参数	必填	描述
id	是（路径参数）	Availability 对象 ID
include_filtered	否（查询参数）	包含被筛除的高价动态定价结果

响应字段（Trip 对象）

字段	描述
Cabin	经济舱、高级经济舱、商务舱、头等舱
MileageCost	积分价格（整数）
AllianceCost	通过联盟合作计划预订的价格（整数）
TotalTaxes	税费，单位为美分（除以 100 得到美元）
TaxesCurrency	货币代码（为空时表示 USD）
RemainingSeats	剩余座位数
Stops	经停次数
TotalDuration	时长（分钟）
Carriers	执飞航空公司
FlightNumbers	航班号字符串
DepartsAt	出发时间（机场当地时间）
ArrivesAt	到达时间（机场当地时间）
AvailabilitySegments	单个航段组成的数组
Source	里程计划

响应还包括：

• booking_links[]，其中包含直接预订 URL 的 label、link 和布尔值 primary
• origin_coordinates 和 destination_coordinates（纬度/经度）

行程航段字段

AvailabilitySegments 中的每个航段：

字段	描述
FlightNumber	例如，"TK800"
AircraftCode	例如，"77W"
AircraftName	例如，"77W"
OriginAirport	航段出发地
DestinationAirport	航段目的地
DepartsAt	出发时间（机场当地时间）
ArrivesAt	到达时间（机场当地时间）
FareClass	预订舱位字母代码（例如，"I"、"X"）
Distance	航段距离，单位为英里
Order	航段顺序（从 0 开始）

批量查询空位

从一个里程计划中检索大量结果。适用于广泛的区域探索（例如，“北美至欧洲所有 United 商务舱航班”）。

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/availability?source=united&origin_region=North%20America&destination_region=Europe&cabin=business&start_date=2026-08-01&end_date=2026-09-30" | jq '.'

参数

参数	必填	描述
source	是	单个里程计划
cabin	否	经济舱、高级经济舱、商务舱、头等舱
start_date	否	YYYY-MM-DD
end_date	否	YYYY-MM-DD
origin_region	否	北美、南美、非洲、亚洲、欧洲、大洋洲
destination_region	否	同上
include_filtered	否	布尔值。显示被筛除的动态定价结果。
take	否	10-1000，默认值为 500
skip	否	分页偏移量
cursor	否	来自上一条响应

获取航线

列出某个里程计划的所有受监控航线。适用于了解哪些城市对已有缓存数据。

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/routes?source=united" | jq '.'

返回航线对象数组：

字段	描述
OriginAirport	出发机场代码
DestinationAirport	到达机场代码
OriginRegion	出发地区名称
DestinationRegion	到达地区名称
NumDaysOut	提前扫描此航线的天数
Distance	航线距离
Source	里程计划

实时搜索

实时搜索任意城市对（不限于受监控的航线）。需要商业协议。 Pro 用户无法通过 API 使用。

响应时间为 5-15 秒。请使用指数退避实现完善的错误处理。

curl -s -X POST -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin_airport":"SFO","destination_airport":"NRT","departure_date":"2026-08-15","source":"united","seat_count":2}' \
  "https://seats.aero/partnerapi/live" | jq '.'

参数（JSON 请求体）

参数	必填	描述
origin_airport	是	单个机场代码
destination_airport	是	单个机场代码
departure_date	是	YYYY-MM-DD
source	是	单个里程计划
seat_count	否	1-9，默认为 1
disable_filters	否	禁用所有筛选条件（动态定价和机场不匹配）
show_dynamic_pricing	否	仅禁用动态定价筛选条件，保留机场筛选

重要： 实时搜索返回的 ID 并非真实 ID，无法用于其他 Seats.aero API（获取行程等）。实时搜索结果是临时的。

分页

所有列表端点均使用 skip + cursor。首次调用时省略两者。从响应中保存 cursor 值。后续调用时传入 cursor，并将 skip 增加收到的结果数量。

cursor 是 Unix 时间戳。请将其视为不透明值。不同页面之间可能偶尔出现重复项。请按 ID 去重。

实用的 jq 筛选器

# Business class availability sorted by cheapest miles
... | jq '[.data[] | select(.JAvailable == true) | {date: .Date, origin: .Route.OriginAirport, dest: .Route.DestinationAirport, miles: (.JMileageCost | tonumber), seats: .JRemainingSeats, airlines: .JAirlines, source: .Source, direct: .JDirect}] | sort_by(.miles)'

# Saver vs dynamic detection: if miles < threshold, likely saver
# AA: J saver ~57.5K for transatlantic, dynamic 100K+
# United: J saver ~60-80K for transatlantic, dynamic 100K+
... | jq '[.data[] | select(.JAvailable == true) | {date: .Date, miles: (.JMileageCost | tonumber), source: .Source, type: (if (.JMileageCost | tonumber) < 80000 then "likely_saver" else "dynamic" end)}]'

# Economy availability with 2+ seats
... | jq '[.data[] | select(.YAvailable == true and .YRemainingSeats >= 2) | {date: .Date, origin: .Route.OriginAirport, dest: .Route.DestinationAirport, miles: (.YMileageCost | tonumber), seats: .YRemainingSeats, source: .Source}] | sort_by(.miles)'

# All available cabins for a date range
... | jq '[.data[] | {date: .Date, origin: .Route.OriginAirport, dest: .Route.DestinationAirport, source: .Source, economy: (if .YAvailable then .YMileageCost else null end), business: (if .JAvailable then .JMileageCost else null end), first: (if .FAvailable then .FMileageCost else null end)}]'

# Direct flights only in business
... | jq '[.data[] | select(.JAvailable == true and .JDirect == true) | {date: .Date, miles: .JMileageCost, airlines: .JAirlines, source: .Source}]'

# Check data freshness (stale = potential phantom)
... | jq '[.data[] | {date: .Date, source: .Source, last_seen: .ComputedLastSeen}]'

工作流：行程规划搜索

1. 缓存搜索多个机场和日期范围，查看有哪些可用选项
2. 比较计划：检查同一路线中哪个 source 所需里程最少
3. 区分 Saver 与动态定价：较低价格（例如，AA 跨大西洋航线的商务舱为 57.5K）= Saver。较高价格（100K+）= 动态定价。
4. 务必获取有希望的可用性 ID 的行程详情——不要只看搜索摘要。搜索摘要（JMileageCost）只显示里程成本最低的行程。行程详情会显示所有可用选项，包括摘要中隐藏的 Standard/动态定价等级。对于涉及 2 位或更多旅客的任何搜索，这都是必需步骤。
5. 展示结果前，应用中途停留筛选条件（见下文）。
6. 确认数据时效性：检查 ComputedLastSeen。如果数据已过时（数小时前），该可用性可能是虚假的。
7. 交叉核对：转点前，查看航空公司官网或致电确认
8. 使用行程响应中的 booking_links，直接在各计划的网站上预订
9. 与 AwardWallet 余额交叉核对，确认积分充足

中途停留质量筛选

获取行程详情后，务必计算每个行程的中途停留时间。标记所有超过 3 小时的中途停留。 不要仅仅因为某个行程最便宜，就不加说明地将中途停留体验不佳的行程作为推荐。

如果最便宜的选项中途停留超过 3 小时：

1. 明确标注后展示："⚠️ 在 FRA 中途停留 8 小时"
2. 同时自动列出下一个最便宜且中途停留少于 3 小时的行程
3. 让用户自行决定积分节省是否值得等待——绝不要不加说明地替用户做决定

原因： Saver 库存通常价格最低，但航线安排也最差（中途停留时间长、转机安排不合理）。Standard 库存的里程成本通常高出 20-30%，但行程体验显著更好。最便宜的奖励机票并不总是最好的奖励机票。

# Calculate layover duration from trip segments
# TotalDuration = full trip (gate to gate including layovers)
# Sum of individual segment durations = pure flight time
# Layover = TotalDuration - sum(segment durations)
# Flag if any single layover exceeds 180 minutes

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/trips/{id}" | jq '
  .data[] | {
    miles: .MileageCost,
    flights: .FlightNumbers,
    total_min: .TotalDuration,
    segments: [.AvailabilitySegments[] | {
      flight: .FlightNumber,
      from: .OriginAirport,
      to: .DestinationAirport,
      departs: .DepartsAt,
      arrives: .ArrivesAt
    }]
  }
'

结果可能为空的原因

1. 没有放出可兑换奖励座位。 大多数计划只向合作伙伴显示奖励座位。请查看航空公司官网。
2. 精英会员／身份限制。 部分座位仅对精英会员或持卡人可见。
3. 未监控该航线。 如果航线不在 Get Routes 中，缓存搜索就不会包含该航线。实时搜索可以查询任何航线。
4. 搜索时间范围限制。 各航空公司放出奖励座位的提前时间不同。请查看放票日期工具。
5. 座位已被预订。 奖励座位的可用情况不断变化。设置提醒，以便有座位放出时收到通知。

专用工具（仅限 Web 界面）

这些工具可在 seats.aero 网站上使用，但无法通过 Partner API 使用：

• Alaska 升舱查询工具（seats.aero/alaska/upgrades）：使用 Atmos Gold Guest Upgrade 证书，为 Alaska 精英会员查找可确认的升舱座位。这是一款专门用于扫描升舱可用情况的工具。
• Etihad 头等舱查询工具（seats.aero/etihad/first）：专门追踪新放出的 Etihad 头等舱座位。Etihad F 座位稀少，备受追捧。与常规搜索相比，此工具能更快显示新放出的座位。
• 价格历史记录：可在 Web 界面查看票价随时间的变化趋势，但 API 不支持。使用 seats-aero-web 技能（通过 Patchright 进行浏览器自动化）访问价格历史图表。

提醒功能

在 seats.aero 上创建提醒时：

• 时间筛选条件：提醒筛选条件中提供起飞和抵达时间范围。适用于避开红眼航班或确保早晨抵达。
• 舱位、航线和计划筛选条件：标准提醒参数。
• 有符合条件的座位时，系统会通过电子邮件或推送通知提醒你。

第三方集成

Pro 账户持有者可通过网站上的“Connect seats.aero”按钮将 seats.aero 连接到第三方应用。

• aeroconnections.app（由 @wavydavy 开发）：可视化工具，显示从指定机场出发的可用联程航班。使用 Pro 账户登录，即可查看当前奖励座位的可视化地图。此工具有助于探索你可能不会想到去搜索的航线方案。

注意事项

• 响应中的所有时间均为机场当地时间。
• TotalTaxes 的单位是美分（除以 100 即为美元）。
• 可用性对象中的 MileageCost 是字符串；行程对象中的该字段是整数。
• 行程对象中的 AllianceCost 表示通过联盟合作伙伴预订的费用。
• 动态定价筛选条件默认启用。传入 include_filtered=true 可查看全部结果。
• 可用性数据经过缓存，并非实时数据。请查看 ComputedLastSeen 了解数据的新鲜程度。
• Pro 用户：每天可调用 API 1,000 次。失败的实时搜索不计入次数。
• 免费用户只能搜索未来 30 天内的行程。Pro 用户可搜索 60 天以上。
• 搜索后的筛选条件（最高积分、经停次数、飞行时长等）现在会直接应用于航班详情结果，而不只是搜索结果列表。