Flyan

Flyan SDK

一个开源的非官方 API 封装，用于获取 Ryanair 航班数据。

提示

新增：面向 AI Agent 的 MCP 服务。 将 Flyan 接入 Claude Desktop、 Claude Code 或 Cursor，即可通过自然语言搜索 Ryanair 航班。 前往 MCP 快速入门。

目录

• 安装
• 快速开始
• API 参考
• 数据模型
• 示例
• 探索模式
• 与 Claude、Cursor 和其他 MCP 客户端搭配使用
• 支持的机场
• 支持的货币
• 速率限制
• 贡献
• 免责声明

安装

pip install Flyan

或者使用 uv：

uv add Flyan

快速开始

from datetime import datetime
from flyan import RyanAir, FlightSearchParams

# Initialize the client
client = RyanAir(currency="EUR")

# Set up search parameters
search_params = FlightSearchParams(
    from_airport="DUB",  # Dublin
    to_airport="BCN",    # Barcelona
    from_date=datetime(2025, 8, 15),
    to_date=datetime(2025, 8, 20),
    max_price=200
)

# Search for one-way flights
flights = client.get_oneways(search_params)

# Display results
for flight in flights:
    print(f"Flight {flight.flight_number}: {flight.departure_airport.name} → {flight.arrival_airport.name}")
    print(f"Departure: {flight.departure_date}")
    print(f"Price: {flight.price} {flight.currency}")
    print("---")

API 参考

RyanAir 类

构造函数

RyanAir(currency: str = "EUR")

创建一个新的 RyanAir 客户端实例。

参数：

• currency（str，可选）：定价时使用的首选货币。默认为 "EUR"。必须是支持的货币列表中的有效货币代码。

示例：

# Default EUR currency
client = RyanAir()

# Specific currency
client = RyanAir(currency="USD")

方法

get_oneways(params: FlightSearchParams) -> list[Flight]

搜索单程航班。

参数：

• params（FlightSearchParams）：搜索参数

返回值：

• list[Flight]：可用航班列表

FlightSearchParams 类

航班搜索参数。

FlightSearchParams(
    from_airport: str,
    from_date: datetime,
    to_date: datetime,
    destination_country: Optional[str] = None,
    max_price: Optional[int] = None,
    to_airport: Optional[str] = None,
    departure_time_from: Optional[str] = "00:00",
    departure_time_to: Optional[str] = "23:59"
)

参数：

• from_airport（str）：出发机场的 IATA 代码（例如 "DUB"）
• from_date（datetime）：最早出发日期
• to_date（datetime）：最晚出发日期
• destination_country（str，可选）：目的地国家代码
• max_price（int，可选）：最高价格筛选条件
• to_airport（str，可选）：到达机场的 IATA 代码
• departure_time_from（str，可选）：最早出发时间（HH:MM 格式）
• departure_time_to（str，可选）：最晚出发时间（HH:MM 格式）

示例：

from datetime import datetime

params = FlightSearchParams(
    from_airport="DUB",
    from_date=datetime(2025, 8, 15),
    to_date=datetime(2025, 8, 20),
    to_airport="BCN",
    max_price=150,
    departure_time_from="08:00",
    departure_time_to="18:00"
)

ReturnFlightSearchParams 类

往返航班搜索的扩展参数。

ReturnFlightSearchParams(
    # All FlightSearchParams fields plus:
    return_date_from: datetime,
    return_date_to: datetime,
    inbound_departure_time_from: Optional[str] = "00:00",
    inbound_departure_time_to: Optional[str] = "23:59"
)

数据模型

Flight

表示单个航班。

属性：

• departure_airport（Airport）：出发机场信息
• arrival_airport（Airport）：到达机场信息
• departure_date（datetime）：出发日期和时间
• arrival_date（datetime）：到达日期和时间
• price（float）：航班价格
• currency（str）：价格货币
• flight_key（str）：航班唯一标识符
• flight_number（str）：航班号
• previous_price（Optional[str | float]）：可用时显示的之前价格

Airport

表示机场信息。

属性：

• country_name（str）：国家名称
• iata_code（str）：机场 IATA 代码
• name（str）：机场名称
• seo_name（str）：适用于 SEO 的名称
• city_name（str）：城市名称
• city_code（str）：城市代码
• city_country_code（str）：国家代码

ReturnFlight

表示往返航班预订。

属性：

• outbound (Flight)：去程航班
• inbound (Flight)：返程航班
• summary_price (float)：两程航班的总价
• summary_currency (str)：总价所用的货币
• previous_price (str | float)：如有，表示之前的总价

NetworkAirport

表示 Ryanair 实时航线网络中的机场。由探索方法返回。

属性：

• iata_code (str)：IATA 机场代码
• name (str)：机场名称
• seo_name (str)：适合 SEO 的名称
• country_code (str)：小写 ISO2 国家代码（例如 "ie"、"es"）
• city_code (str)：城市代码（例如 "LONDON"、"DUBLIN"）
• region_code (Optional[str])：地区代码（例如 "SCOTLAND"、"ANDALUSIA"）
• currency_code (str)：当地货币代码
• time_zone (str)：IANA 时区（例如 "Europe/Dublin"）
• base (bool)：如果这是 Ryanair 的基地机场，则为 True
• latitude (float), longitude (float)：坐标
• routes (list[str])：原始航线字符串（全年）
• seasonal_routes (list[str])：原始航线字符串（仅季节性）
• categories (list[str])：Ryanair 分配的营销类别
• aliases (list[str])：别名

辅助方法：airport_routes()、country_routes()、seasonal_airport_routes()、 typed_routes()、typed_seasonal_routes()。

DestinationFare

由 explore_with_fares() 返回。将可抵达的目的地与其最低抽样票价配对；如果价格查询返回了票价的话。

属性：

• airport (NetworkAirport)：目的地机场
• fare (Optional[Flight])：该时间范围内抽样得到的最低票价；如果该航线在网络中，但没有返回有价库存（时间范围内无航班、已售罄等），则为 None

示例

按国家/地区搜索

# Search flights to any airport in Spain
params = FlightSearchParams(
    from_airport="DUB",
    destination_country="ES",
    from_date=datetime(2025, 9, 1),
    to_date=datetime(2025, 9, 7)
)

flights = client.get_oneways(params)

按时间和价格筛选

# Morning flights under €100
params = FlightSearchParams(
    from_airport="STN",  # London Stansted
    to_airport="DUB",    # Dublin
    from_date=datetime(2025, 8, 1),
    to_date=datetime(2025, 8, 5),
    max_price=100,
    departure_time_from="06:00",
    departure_time_to="12:00"
)

flights = client.get_oneways(params)

错误处理

from flyan import RyanairException

try:
    flights = client.get_oneways(params)
    if not flights:
        print("No flights found for the given criteria")
except RyanairException as e:
    print(f"Ryanair API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

探索模式

探索模式回答“我从这里实际上可以飞到哪里？”这个问题。它会读取一次 Ryanair 的实时网络元数据，并提供从任意机场出发可抵达的目的地，还可选择分组、筛选，或关联日期范围内的最低票价。

以下所有方法在 RyanAir 和 AsyncRyanAir 上均可用。

列出所有目的地

destinations = client.get_destinations("DUB")

for airport in destinations:
    print(f"{airport.iata_code} {airport.name} ({airport.country_code})")

按国家/地区、区域或城市筛选

# All Scottish airports DUB flies to
in_scotland = client.get_destinations_in_region("DUB", "SCOTLAND")

# All London airports DUB flies to (LGW, LTN, STN)
in_london = client.get_destinations_in_city("DUB", "LONDON")

# All Spanish airports DUB flies to
in_spain = client.get_destinations_in_country("DUB", "es")

国家代码为小写 ISO2。区域和城市代码来自实时网络（大写，例如 SCOTLAND、ANDALUSIA、COSTA_DE_SOL、LONDON、MILAN）。

对目的地分组

# {country_code: [airports]}
by_country = client.explore_by_country("DUB")

print(f"DUB flies to {len(by_country)} countries")
for country, airports in sorted(by_country.items()):
    codes = ", ".join(a.iata_code for a in airports)
    print(f"  {country}: {codes}")

# {region_code: [airports]}
by_region = client.explore_by_region("DUB")

没有 region_code 的机场会归入空字符串键下，调用方可自行决定是否显示或删除它们。

仅限季节性目的地

seasonal = client.get_seasonal_destinations("DUB")

上游提供的 Ryanair seasonalRoutes 列表数据较少，因此在夏季/冬季时刻表切换期以外，此方法通常会返回 []。提供此方法后，调用方无需查看原始航线字符串。

获取目的地及其最低票价

explore_with_fares() 会将网络目的地与 oneWayFares 查询结果关联，因此每个目的地都会附带抽样得到的最低 Flight（如果该航线在此时间范围内没有返回票价，则为 None）。这需要一次网络调用和一次票价调用。

from datetime import datetime, timedelta

start = datetime.now() + timedelta(days=14)
end = start + timedelta(days=7)

results = client.explore_with_fares("DUB", start, end, max_price=100)

priced = [d for d in results if d.fare is not None]
cheapest_first = sorted(priced, key=lambda d: d.fare.price)

for d in cheapest_first[:10]:
    print(f"{d.airport.iata_code} {d.airport.name}: "
          f"{d.fare.price} {d.fare.currency}")

异步用法

AsyncRyanAir 提供了所有探索方法的对应版本：

import asyncio
from flyan import AsyncRyanAir

async def main():
    async with AsyncRyanAir() as client:
        by_country = await client.explore_by_country("DUB")
        print(f"{len(by_country)} countries reachable from DUB")

asyncio.run(main())

如果连续调用多个探索方法，请将传输封装在 CachingTransport 中，以便网络元数据只获取一次并重复使用。

与 Claude、Cursor 和其他 MCP 客户端搭配使用

重要

只需运行两条命令：

uv tool install "Flyan[mcp]"
claude mcp add flyan flyan-mcp

现在，你的 Agent 可以通过自然语言搜索 Ryanair 航班。无需 API 密钥，也无需账户。

Flyan 提供可选的 Model Context Protocol 服务，让你的 Agent 可以通过自然语言提示词搜索 Ryanair 票价，例如 "帮我找一张 8 月从都柏林飞往西班牙、价格低于 €150 的便宜机票"，或 "7 月从 DUB 飞往 BCN，哪一天的票价最低"。

快速入门

1. 安装带 MCP extra 的 Flyan：

uv tool install "Flyan[mcp]"

或使用 pip：

pipx install "Flyan[mcp]"

这会在你的 PATH 上安装一个 flyan-mcp 控制台脚本。

2. 将其添加到你的 Agent：

Claude Code（单行命令）：

claude mcp add flyan flyan-mcp

Claude Desktop：在 macOS 上打开 ~/Library/Application Support/Claude/claude_desktop_config.json （或在 Windows 上打开 %APPDATA%\Claude\claude_desktop_config.json），并添加：

{
  "mcpServers": {
    "flyan": {
      "command": "flyan-mcp"
    }
  }
}

然后重启 Claude Desktop。

Cursor：设置 → MCP → 添加新服务，名称为 flyan，命令为 flyan-mcp。

货币

服务默认以 EUR 返回价格。若要使用其他货币，请在启动 flyan-mcp 前，将 FLYAN_CURRENCY 环境变量设为任意受支持的 ISO 4217 代码：

FLYAN_CURRENCY=GBP flyan-mcp

或者通过 Agent 的 MCP 配置传入：

{
  "mcpServers": {
    "flyan": {
      "command": "flyan-mcp",
      "env": { "FLYAN_CURRENCY": "GBP" }
    }
  }
}

未知或不受支持的代码会静默回退到 EUR。

3. 试用。 向你的 Agent 提问：

“帮我找一张从都柏林飞往西班牙任意地点的单程机票，时间在 8 月第一周，价格低于 €150。”

Agent 应调用 find_flights 并设置 destination_country="es"，然后总结最便宜的选项。

暴露的工具

该服务暴露了四个精选工具，方便 Agent 可靠地进行选择：

• find_flights 用于单程搜索，可选国家、IATA 代码或价格筛选条件
• find_anywhere_under 用于“£X 以下可以去哪里”的提示词
• explore_destinations 用于“从 X 可以飞到哪些国家”
• cheapest_per_day 用于“本月哪一天从 X 飞往 Y 最便宜”

无需 API 密钥、账户或速率限制设置。Ryanair 的 API 无需身份验证，且该服务会在多次调用间复用同一个 RyanAir 客户端。

受支持的机场

SDK 支持 Ryanair 网络中的所有机场。机场代码必须是有效的 3 个字母 IATA 代码。机场实时列表通过 client.get_network() 从 Ryanair 的聚合端点获取；遍历 network.airports 可获取完整列表。

常见机场包括：

• DUB - 都柏林
• STN - 伦敦斯坦斯特德
• BCN - 巴塞罗那
• MAD - 马德里
• FCO - 罗马菲乌米奇诺
• BRU - 布鲁塞尔
• AMS - 阿姆斯特丹

受支持的货币

SDK 支持多种货币，其中一些常见货币包括：

• EUR - 欧元
• USD - 美元
• GBP - 英镑
• CHF - 瑞士法郎

完整列表请参见 currencies.json。

速率限制

SDK 内置了带指数退避的自动重试逻辑，用于处理速率限制和临时 API 问题。请求失败时，最多会重试 5 次，然后放弃。

贡献

这是一个开源项目。欢迎贡献！

免责声明

这是一个非官方 API 封装，与 Ryanair 没有隶属关系。使用风险自负，并确保遵守 Ryanair 的服务条款。