Code examples

This page showcases all 11 example files from the examples/ directory. Each example is a complete, runnable Python script that demonstrates specific features of the Fli library.

Running examples

Using uv (recommended)
After installing

# Run any example with uv (automatically handles dependencies)
uv run python examples/basic_one_way_search.py

# Or from the project root
uv run python -m examples.basic_one_way_search

# Install the package first
pip install fli

# Then run examples directly
python examples/basic_one_way_search.py

Basic examples

Basic one-way search

File: examples/basic_one_way_search.py Demonstrates the simplest flight search between two airports on a specific date. Shows core API usage with basic filters. Features:

Single passenger search
Non-stop flights filter
Economy class
Sort by cheapest price
Result processing and display

from datetime import datetime, timedelta
from fli.models import (
    Airport,
    FlightSearchFilters,
    FlightSegment,
    PassengerInfo,
    SeatType,
    MaxStops,
    SortBy,
)
from fli.search import SearchFlights

# Create search filters
filters = FlightSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
        )
    ],
    seat_type=SeatType.ECONOMY,
    stops=MaxStops.NON_STOP,
    sort_by=SortBy.CHEAPEST,
)

# Search flights
search = SearchFlights()
flights = search.search(filters)

# Process results
for flight in flights:
    print(f"💰 Price: ${flight.price}")
    print(f"⏱️ Duration: {flight.duration} minutes")
    print(f"✈️ Stops: {flight.stops}")
    
    for leg in flight.legs:
        print(f"\n🛫 Flight: {leg.airline.value} {leg.flight_number}")
        print(f"📍 From: {leg.departure_airport.value} at {leg.departure_datetime}")
        print(f"📍 To: {leg.arrival_airport.value} at {leg.arrival_datetime}")

Round-trip search

File: examples/round_trip_search.py Shows how to search for round-trip flights with outbound and return segments. Demonstrates handling the tuple structure of round-trip results. Features:

Two flight segments (outbound and return)
Round-trip trip type
Combined price calculation
Tuple unpacking for results

from datetime import datetime, timedelta
from fli.models import (
    Airport,
    FlightSearchFilters,
    FlightSegment,
    PassengerInfo,
    TripType,
)
from fli.search import SearchFlights

# Create flight segments for round trip
outbound_date = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")
return_date = (datetime.now() + timedelta(days=37)).strftime("%Y-%m-%d")

flight_segments = [
    FlightSegment(
        departure_airport=[[Airport.JFK, 0]],
        arrival_airport=[[Airport.LAX, 0]],
        travel_date=outbound_date,
    ),
    FlightSegment(
        departure_airport=[[Airport.LAX, 0]],
        arrival_airport=[[Airport.JFK, 0]],
        travel_date=return_date,
    ),
]

# Create filters
filters = FlightSearchFilters(
    trip_type=TripType.ROUND_TRIP,
    passenger_info=PassengerInfo(adults=1),
    flight_segments=flight_segments,
)

# Search flights
search = SearchFlights()
results = search.search(filters)

# Process results - note the tuple structure
for outbound, return_flight in results:
    print("\nOutbound Flight:")
    for leg in outbound.legs:
        print(f"Flight: {leg.airline.value} {leg.flight_number}")
        print(f"Departure: {leg.departure_datetime}")
        print(f"Arrival: {leg.arrival_datetime}")
    
    print("\nReturn Flight:")
    for leg in return_flight.legs:
        print(f"Flight: {leg.airline.value} {leg.flight_number}")
        print(f"Departure: {leg.departure_datetime}")
        print(f"Arrival: {leg.arrival_datetime}")
    
    print(f"\nTotal Price: ${outbound.price + return_flight.price}")

Date range search

File: examples/date_range_search.py Demonstrates searching across a date range to find the cheapest dates to fly. Features:

SearchDates for flexible date searching
30-day date range
DatePrice result processing

from datetime import datetime, timedelta
from fli.models import Airport, DateSearchFilters, FlightSegment, PassengerInfo
from fli.search import SearchDates

# Create future dates
base_date = datetime.now() + timedelta(days=30)
travel_date = base_date.strftime("%Y-%m-%d")
from_date = base_date.strftime("%Y-%m-%d")
to_date = (base_date + timedelta(days=30)).strftime("%Y-%m-%d")

# Create filters
filters = DateSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date=travel_date,
        )
    ],
    from_date=from_date,
    to_date=to_date,
)

# Search dates
search = SearchDates()
results = search.search(filters)

# Process results
for date_price in results:
    print(f"Date: {date_price.date}, Price: ${date_price.price}")

Advanced examples

Complex flight search

File: examples/complex_flight_search.py Demonstrates advanced filtering with multiple passengers, airline preferences, layover restrictions, and more. Features:

Multiple passenger types (adults, children, infants)
Business class search
Airline filtering (British Airways and Virgin Atlantic)
Maximum duration limit
Layover restrictions (preferred airports and max duration)
Detailed result display

See the full code in examples/complex_flight_search.py. This example shows how to combine multiple filters for precise search requirements.

Time restrictions search

File: examples/time_restrictions_search.py Shows how to filter flights by specific departure and arrival time windows. Features:

TimeRestrictions for departure window (6 AM - 10 AM)
Arrival time constraints (12 PM - 6 PM)
Morning flight preference
Time formatting in results

from fli.models import TimeRestrictions

filters = FlightSearchFilters(
    trip_type=TripType.ONE_WAY,
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
            time_restrictions=TimeRestrictions(
                earliest_departure=6,   # 6 AM
                latest_departure=10,    # 10 AM
                earliest_arrival=12,    # 12 PM
                latest_arrival=18,      # 6 PM
            ),
        )
    ],
)

Date search with preferences

File: examples/date_search_with_preferences.py Demonstrates date-based searching with post-processing filters for specific day preferences (e.g., weekends only). Features:

Date range searching
Weekend-only filtering (Saturday/Sunday)
Premium economy class
Day-of-week detection
Custom result formatting

# Search across date range
results = search.search(filters)

# Filter for weekends only
weekend_results = [
    r for r in results
    if r.date[0].weekday() >= 5  # Saturday = 5, Sunday = 6
]

print(f"Found {len(weekend_results)} weekend flights:")
for result in weekend_results:
    day_name = result.date[0].strftime("%A")
    date_str = result.date[0].strftime("%Y-%m-%d")
    print(f"{day_name}, {date_str}: ${result.price}")

Enterprise examples

Complex round-trip validation

File: examples/complex_round_trip_validation.py Enterprise-level round-trip search with comprehensive date validation, complex passenger configurations, and detailed requirements. Features:

Date validation function (future dates, max duration)
Multiple passengers with infants
Time restrictions for both outbound and return
Business class
Layover optimization
Multi-airline preferences
Detailed error handling

def validate_trip_dates(outbound_date_str: str, return_date_str: str):
    """Validate trip dates with comprehensive checks."""
    today = datetime.now().date()
    outbound_date = datetime.strptime(outbound_date_str, "%Y-%m-%d").date()
    return_date = datetime.strptime(return_date_str, "%Y-%m-%d").date()
    
    if outbound_date <= today:
        raise ValueError("Outbound date must be in the future")
    if return_date <= outbound_date:
        raise ValueError("Return date must be after outbound date")
    if return_date - outbound_date > timedelta(days=30):
        raise ValueError("Trip duration cannot exceed 30 days")
    
    print(f"✓ Dates validated: {outbound_date} to {return_date}")
    return outbound_date, return_date

This example is perfect for production applications that need robust validation and error handling.

Advanced date search validation

File: examples/advanced_date_search_validation.py Comprehensive date range searching with validation, stay duration constraints, and weekend trip optimization. Features:

Date range validation function
Stay duration constraints (min/max days)
Round-trip date searches with variable durations
Weekend departure filtering
Time restrictions
Top 5 results sorted by price
Detailed validation error messages

Ideal for building flexible booking tools that need to validate user input and find optimal weekend trips.

Utility examples

Price tracking

File: examples/price_tracking.py Demonstrates tracking flight prices over multiple days to analyze trends and find deals. Features:

Multi-day price monitoring
Price history storage
Statistical analysis (min, max, average)
Time-based iteration
Trend identification concepts

def track_prices(days=7):
    """Track flight prices over a specified number of days."""
    search = SearchDates()
    price_history = {}
    
    for day in range(days):
        print(f"Day {day + 1}: Searching for prices...")
        results = search.search(filters)
        
        # Store prices
        for result in results:
            date_str = result.date[0].strftime("%Y-%m-%d")
            if date_str not in price_history:
                price_history[date_str] = []
            price_history[date_str].append(result.price)
        
        # Wait for next check (24 hours in production)
        if day < days - 1:
            time.sleep(86400)
    
    return price_history

# Analyze results
for date, prices in price_history.items():
    min_price = min(prices)
    max_price = max(prices)
    avg_price = sum(prices) / len(prices)
    print(f"{date}: Min: ${min_price:.2f}, Max: ${max_price:.2f}, Avg: ${avg_price:.2f}")

Error handling with retries

File: examples/error_handling_with_retries.py Shows robust error handling patterns with both simple and advanced retry logic. Features:

Simple retry implementation (no dependencies)
Advanced retry with tenacity library
Exponential backoff
Graceful degradation
Optional dependency handling

def simple_retry_search(filters: FlightSearchFilters, max_attempts=3):
    """Simple retry logic without external dependencies."""
    search = SearchFlights()
    
    for attempt in range(max_attempts):
        try:
            print(f"Attempt {attempt + 1}/{max_attempts}")
            results = search.search(filters)
            if not results:
                raise ValueError("No results found")
            return results
        except Exception as e:
            print(f"Search failed: {str(e)}")
            if attempt == max_attempts - 1:
                raise
            print("Retrying...")
    
    return None

# Advanced retry with tenacity
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=4, max=60))
def search_with_retry(filters: FlightSearchFilters):
    """Advanced retry logic with exponential backoff."""
    search = SearchFlights()
    results = search.search(filters)
    if not results:
        raise ValueError("No results found")
    return results

The HTTP client already includes retry logic at the network level. These examples show application-level retry patterns for additional robustness.

Result processing

File: examples/result_processing.py Demonstrates advanced result analysis and data format conversion. Features:

Convert results to dictionary format
Basic statistical analysis (no dependencies)
Pandas integration for advanced analysis
CSV export capabilities
Price and duration statistics
Airline distribution analysis

def analyze_results(results: list[FlightResult]) -> dict:
    """Convert results to dictionary format for analysis."""
    flights_data = []
    
    for flight in results:
        for leg in flight.legs:
            flights_data.append({
                "price": flight.price,
                "total_duration": flight.duration,
                "stops": flight.stops,
                "airline": leg.airline.value,
                "flight_number": leg.flight_number,
                "departure_airport": leg.departure_airport.value,
                "arrival_airport": leg.arrival_airport.value,
                "departure_time": leg.departure_datetime,
                "arrival_time": leg.arrival_datetime,
                "leg_duration": leg.duration,
            })
    
    return flights_data

# Basic analysis
prices = [flight.price for flight in results]
print(f"Price range: ${min(prices)} - ${max(prices)}")
print(f"Average price: ${sum(prices) / len(prices):.2f}")

# Pandas analysis (optional)
if PANDAS_AVAILABLE:
    df = pd.DataFrame(flights_data)
    print(df["price"].describe())
    print(df.groupby("airline")["total_duration"].mean().sort_values())
    df.to_csv("flight_analysis.csv", index=False)

Example categories

Basic examples

basic_one_way_search.py
round_trip_search.py
date_range_search.pyCore functionality and simple usage patterns

Advanced examples

complex_flight_search.py
time_restrictions_search.py
date_search_with_preferences.pyMultiple filters and constraints

Enterprise examples

complex_round_trip_validation.py
advanced_date_search_validation.pyProduction-ready validation and complex requirements

Utility examples

price_tracking.py
error_handling_with_retries.py
result_processing.pyRobust implementation and data analysis

Common patterns

Airport selection

from fli.models import Airport

# Major US airports
Airport.JFK  # New York JFK
Airport.LAX  # Los Angeles
Airport.ORD  # Chicago O'Hare
Airport.DFW  # Dallas/Fort Worth
Airport.SFO  # San Francisco
Airport.BOS  # Boston
Airport.MIA  # Miami
Airport.SEA  # Seattle

# International airports
Airport.LHR  # London Heathrow
Airport.CDG  # Paris Charles de Gaulle
Airport.NRT  # Tokyo Narita
Airport.SYD  # Sydney

Date handling

from datetime import datetime, timedelta

# Future dates (required for searches)
future_date = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")

# Date ranges
from_date = "2024-06-01"
to_date = "2024-06-30"

# Dynamic date calculation
outbound = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")
return_date = (datetime.now() + timedelta(days=37)).strftime("%Y-%m-%d")

Passenger configuration

from fli.models import PassengerInfo

# Single traveler
PassengerInfo(adults=1)

# Couple
PassengerInfo(adults=2)

# Family with children
PassengerInfo(adults=2, children=2, infants_on_lap=1)

Next steps

SearchFlights API

Detailed SearchFlights documentation

SearchDates API

Detailed SearchDates documentation

Library overview

Core concepts and data models

Get Started

MCP Server

CLI Usage

Python Library

Guides

Code examples

Running examples

Basic examples

Basic one-way search

Round-trip search

Date range search

Advanced examples

Complex flight search

Time restrictions search

Date search with preferences

Enterprise examples

Complex round-trip validation

Advanced date search validation

Utility examples

Price tracking

Error handling with retries

Result processing

Example categories

Basic examples

Advanced examples

Enterprise examples

Utility examples

Common patterns

Airport selection

Date handling

Passenger configuration

Next steps

SearchFlights API

SearchDates API

Library overview

​Running examples

​Basic examples

​Basic one-way search

​Round-trip search

​Date range search

​Advanced examples

​Complex flight search

​Time restrictions search

​Date search with preferences

​Enterprise examples

​Complex round-trip validation

​Advanced date search validation

​Utility examples

​Price tracking

​Error handling with retries

​Result processing

​Example categories

Basic examples

Advanced examples

Enterprise examples

Utility examples

​Common patterns

​Airport selection

​Date handling

​Passenger configuration

​Next steps

SearchFlights API

SearchDates API

Library overview

Running examples

Basic examples

Basic one-way search

Round-trip search

Date range search

Advanced examples

Complex flight search

Time restrictions search

Date search with preferences

Enterprise examples

Complex round-trip validation

Advanced date search validation

Utility examples

Price tracking

Error handling with retries

Result processing

Example categories

Common patterns

Airport selection

Date handling

Passenger configuration

Next steps