Models Reference

Core Models

FlightSearchFilters

The main model for configuring flight searches.

from fli.models import FlightSearchFilters, SeatType, MaxStops, SortBy

filters = FlightSearchFilters(
    trip_type=TripType.ONE_WAY,
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[...],
    stops=MaxStops.NON_STOP,
    seat_type=SeatType.ECONOMY,
    sort_by=SortBy.CHEAPEST
)

fli.models.google_flights.FlightSearchFilters

Bases: BaseModel

Complete set of filters for flight search.

This model matches required Google Flights' API structure.

airlines: list[Airline] | None = None class-attribute instance-attribute

flight_segments: list[FlightSegment] instance-attribute

layover_restrictions: LayoverRestrictions | None = None class-attribute instance-attribute

max_duration: PositiveInt | None = None class-attribute instance-attribute

passenger_info: PassengerInfo instance-attribute

price_limit: PriceLimit | None = None class-attribute instance-attribute

seat_type: SeatType = SeatType.ECONOMY class-attribute instance-attribute

sort_by: SortBy = SortBy.NONE class-attribute instance-attribute

stops: MaxStops = MaxStops.ANY class-attribute instance-attribute

trip_type: TripType = TripType.ONE_WAY class-attribute instance-attribute

encode() -> str

URL encode the formatted filters for API request.

Source code in fli/models/google_flights.py

def encode(self) -> str:
    """URL encode the formatted filters for API request."""
    formatted_filters = self.format()
    # First convert the formatted filters to a JSON string
    formatted_json = json.dumps(formatted_filters, separators=(",", ":"))
    # Then wrap it in a list with null
    wrapped_filters = [None, formatted_json]
    # Finally, encode the whole thing
    return urllib.parse.quote(json.dumps(wrapped_filters, separators=(",", ":")))

format() -> list

Format filters into Google Flights API structure.

This method converts the FlightSearchFilters model into the specific nested list/dict structure required by Google Flights' API.

The output format matches Google Flights' internal API structure, with careful handling of nested arrays and proper serialization of enums and model objects.

RETURNS	DESCRIPTION
list	A formatted list structure ready for the Google Flights API request TYPE: list

Source code in fli/models/google_flights.py

def format(self) -> list:
    """Format filters into Google Flights API structure.

    This method converts the FlightSearchFilters model into the specific nested list/dict
    structure required by Google Flights' API.

    The output format matches Google Flights' internal API structure, with careful handling
    of nested arrays and proper serialization of enums and model objects.

    Returns:
        list: A formatted list structure ready for the Google Flights API request

    """

    def serialize(obj):
        if isinstance(obj, Airport) or isinstance(obj, Airline):
            return obj.name
        if isinstance(obj, Enum):
            return obj.value
        if isinstance(obj, list):
            return [serialize(item) for item in obj]
        if isinstance(obj, dict):
            return {key: serialize(value) for key, value in obj.items()}
        if isinstance(obj, BaseModel):
            return serialize(obj.dict(exclude_none=True))
        return obj

    # Format flight segments
    formatted_segments = []
    for segment in self.flight_segments:
        # Format airport codes with correct nesting
        segment_filters = [
            [
                [
                    [serialize(airport[0]), serialize(airport[1])]
                    for airport in segment.departure_airport
                ]
            ],
            [
                [
                    [serialize(airport[0]), serialize(airport[1])]
                    for airport in segment.arrival_airport
                ]
            ],
        ]

        # Time restrictions
        if segment.time_restrictions:
            time_filters = [
                segment.time_restrictions.earliest_departure,
                segment.time_restrictions.latest_departure,
                segment.time_restrictions.earliest_arrival,
                segment.time_restrictions.latest_arrival,
            ]
        else:
            time_filters = None

        # Airlines
        airlines_filters = None
        if self.airlines:
            sorted_airlines = sorted(self.airlines, key=lambda x: x.value)
            airlines_filters = [serialize(airline) for airline in sorted_airlines]

        # Layover restrictions
        layover_airports = (
            [serialize(a) for a in self.layover_restrictions.airports]
            if self.layover_restrictions and self.layover_restrictions.airports
            else None
        )
        layover_duration = (
            self.layover_restrictions.max_duration if self.layover_restrictions else None
        )

        segment_formatted = [
            segment_filters[0],  # departure airport
            segment_filters[1],  # arrival airport
            time_filters,  # time restrictions
            serialize(self.stops.value),  # stops
            airlines_filters,  # airlines
            None,  # placeholder
            segment.travel_date,  # travel date
            [self.max_duration] if self.max_duration else None,  # max duration
            None,  # placeholder
            layover_airports,  # layover airports
            None,  # placeholder
            None,  # placeholder
            layover_duration,  # layover duration
            None,  # emissions
            3,  # constant value
        ]
        formatted_segments.append(segment_formatted)

    # Create the main filters structure
    filters = [
        [],  # empty array at start
        [
            None,  # placeholder
            None,  # placeholder
            serialize(self.trip_type.value),
            None,  # placeholder
            [],  # empty array
            serialize(self.seat_type.value),
            [
                self.passenger_info.adults,
                self.passenger_info.children,
                self.passenger_info.infants_on_lap,
                self.passenger_info.infants_in_seat,
            ],
            [None, self.price_limit.max_price] if self.price_limit else None,
            None,  # placeholder
            None,  # placeholder
            None,  # placeholder
            None,  # placeholder
            None,  # placeholder
            formatted_segments,
            None,  # placeholder
            None,  # placeholder
            None,  # placeholder
            1,  # placeholder (hardcoded to 1)
        ],
        serialize(self.sort_by.value),
        0,  # constant
        0,  # constant
        2,  # constant
    ]

    return filters

FlightResult

Represents a flight search result with complete details.

fli.models.google_flights.FlightResult

Bases: BaseModel

Complete flight search result with pricing and timing.

duration: PositiveInt instance-attribute

legs: list[FlightLeg] instance-attribute

price: NonNegativeFloat instance-attribute

stops: NonNegativeInt instance-attribute

FlightLeg

Represents a single flight segment with airline and timing details.

fli.models.google_flights.FlightLeg

Bases: BaseModel

A single flight leg (segment) with airline and timing details.

airline: Airline instance-attribute

arrival_airport: Airport instance-attribute

arrival_datetime: datetime instance-attribute

departure_airport: Airport instance-attribute

departure_datetime: datetime instance-attribute

duration: PositiveInt instance-attribute

flight_number: str instance-attribute

Enums

SeatType

Available cabin classes for flights.

fli.models.google_flights.SeatType

Bases: Enum

Available cabin classes for flights.

BUSINESS = 3 class-attribute instance-attribute

ECONOMY = 1 class-attribute instance-attribute

FIRST = 4 class-attribute instance-attribute

PREMIUM_ECONOMY = 2 class-attribute instance-attribute

MaxStops

Maximum number of stops allowed in flight search.

fli.models.google_flights.MaxStops

Bases: Enum

Maximum number of stops allowed in flight search.

ANY = 0 class-attribute instance-attribute

NON_STOP = 1 class-attribute instance-attribute

ONE_STOP_OR_FEWER = 2 class-attribute instance-attribute

TWO_OR_FEWER_STOPS = 3 class-attribute instance-attribute

SortBy

Available sorting options for flight results.

fli.models.google_flights.SortBy

Bases: Enum

Available sorting options for flight results.

ARRIVAL_TIME = 4 class-attribute instance-attribute

CHEAPEST = 2 class-attribute instance-attribute

DEPARTURE_TIME = 3 class-attribute instance-attribute

DURATION = 5 class-attribute instance-attribute

NONE = 0 class-attribute instance-attribute

TOP_FLIGHTS = 1 class-attribute instance-attribute

Support Models

PassengerInfo

Configuration for passenger counts.

fli.models.google_flights.PassengerInfo

Bases: BaseModel

Passenger configuration for flight search.

adults: NonNegativeInt = 1 class-attribute instance-attribute

children: NonNegativeInt = 0 class-attribute instance-attribute

infants_in_seat: NonNegativeInt = 0 class-attribute instance-attribute

infants_on_lap: NonNegativeInt = 0 class-attribute instance-attribute

TimeRestrictions

Time constraints for flight departure and arrival.

fli.models.google_flights.TimeRestrictions

Bases: BaseModel

Time constraints for flight departure and arrival in local time.

All times are in hours from midnight (e.g., 20 = 8:00 PM).

earliest_arrival: NonNegativeInt | None = None class-attribute instance-attribute

earliest_departure: NonNegativeInt | None = None class-attribute instance-attribute

latest_arrival: PositiveInt | None = None class-attribute instance-attribute

latest_departure: PositiveInt | None = None class-attribute instance-attribute

PriceLimit

Price constraints for flight search.

fli.models.google_flights.PriceLimit

Bases: BaseModel

Maximum price constraint for flight search.

currency: Currency | None = Currency.USD class-attribute instance-attribute

max_price: PositiveInt instance-attribute