Skip to main content

​
Overview

The SearchFlights class handles searching for specific flights with detailed filters, parsing the results into structured data models. It interfaces directly with Google Flights’ API to find available flights and their details.

​
Class initialization

from fli.search import SearchFlights

searcher = SearchFlights()
Initializes the search client for flight searches. No parameters required.

​
Methods

Search for flights using the given filters. 
def search(
    self,
    filters: FlightSearchFilters,
    top_n: int = 5
) -> list[FlightResult | tuple[FlightResult, FlightResult]] | None
​
filters
FlightSearchFilters
required
Full flight search object including airports, dates, and preferences
​
top_n
int
default:"5"
Number of flights to limit the return flight search to
​
return
list[FlightResult | tuple[FlightResult, FlightResult]] | None
For one-way trips: list of FlightResult objects containing flight detailsFor round-trip: list of tuples containing (outbound FlightResult, return FlightResult) pairsReturns None if no results found
Raises:
  • Exception: If the search fails or returns invalid data
Example: 
from fli.search import SearchFlights
from fli.models import FlightSearchFilters, FlightSegment, Airport
from fli.models.google_flights.base import TripType

# Create search filters
filters = FlightSearchFilters(
    trip_type=TripType.ROUND_TRIP,
    flight_segments=[
        FlightSegment(
            origin=Airport.LAX,
            destination=Airport.JFK,
            travel_date="2026-04-15"
        ),
        FlightSegment(
            origin=Airport.JFK,
            destination=Airport.LAX,
            travel_date="2026-04-22"
        )
    ]
)

# Search for flights
searcher = SearchFlights()
results = searcher.search(filters, top_n=10)

if results:
    for outbound, return_flight in results:
        print(f"${outbound.price} - {outbound.duration} min")

​
Return types

​
FlightResult

Each FlightResult object contains:
​
price
float
Flight price in the search currency
​
duration
int
Total flight duration in minutes
​
stops
int
Number of stops (0 for non-stop)
​
legs
list[FlightLeg]
List of individual flight leg details

​
FlightLeg

Each FlightLeg object contains:
​
airline
Airline
Airline operating the flight leg
​
flight_number
str
Flight number (e.g., “AA123”)
​
departure_airport
Airport
Departure airport code
​
arrival_airport
Airport
Arrival airport code
​
departure_datetime
datetime
Departure date and time
​
arrival_datetime
datetime
Arrival date and time
​
duration
int
Leg duration in minutes

​
Notes

  • For round-trip searches, the method automatically searches for return flights for the top N outbound flights
  • The search client includes automatic rate limiting (10 req/sec) and retries
  • Prices may be 0.0 if price data is unavailable from the API

Build docs developers (and LLMs) love

Get started for freeTalk to us