Metadata-Version: 2.3
Name: flights
Version: 0.2.0
Summary: A Python wrapper for Google Flights API
Home-page: https://github.com/punitarani/fli
Keywords: flights,google-flights,travel,api,flight-search
Author: Punit Arani
Author-email: punit@joinslash.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: curl-cffi (>=0.7.4,<0.8.0)
Requires-Dist: google-genai (>=0.4.0,<0.5.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pydantic (>=2.10.4,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: ratelimit (>=2.2.1,<3.0.0)
Requires-Dist: streamlit (>=1.41.1,<2.0.0)
Requires-Dist: tenacity (>=9.0.0,<10.0.0)
Requires-Dist: typer (>=0.15.1,<0.16.0)
Project-URL: Documentation, https://punitarani.github.io/fli
Project-URL: Repository, https://github.com/punitarani/fli
Description-Content-Type: text/markdown

# Fli 🛫

A powerful Python library that provides programmatic access to Google Flights data with an elegant CLI interface. Search
flights, find the best deals, and filter results with ease.

Try out the live demo at [flightly.streamlit.app](https://flightly.streamlit.app)

> 🚀 **What makes `fli` special?**  
> Unlike other flight search libraries that rely on web scraping, Fli directly interacts with Google Flights' API
> through reverse engineering.
> This means:
> - **Fast**: Direct API access means faster, more reliable results
> - **Zero Scraping**: No HTML parsing, no browser automation, just pure API interaction
> - **Reliable**: Less prone to breaking from UI changes
> - **Modular**: Extensible architecture for easy customization and integration

[![CLI Demo](https://github.com/punitarani/fli/blob/main/data/cli-demo.png)](https://github.com/punitarani/fli/blob/main/data/cli-demo.png)

## Quick Start

```bash
pip install flights
```

```bash
# Install using pipx (recommended for CLI and GUI)
pipx install flights

# Get started with CLI
fli --help

# Launch the GUI
fli app
```

## Features

- 🔍 **Powerful Search**
    - One-way flight searches
    - Flexible departure times
    - Multi-airline support
    - Cabin class selection
    - Stop preferences
    - Custom result sorting

- 💺 **Cabin Classes**
    - Economy
    - Premium Economy
    - Business
    - First

- 🎯 **Smart Sorting**
    - Price
    - Duration
    - Departure Time
    - Arrival Time

- 🛡️ **Built-in Protection**
    - Rate limiting
    - Automatic retries
    - Comprehensive error handling
    - Input validation

## CLI Usage

### Search for Specific Flights

```bash
# Basic search
fli search JFK LHR 2025-10-25

# Advanced search with filters
fli search JFK LHR 2025-10-25 \
    -t 6-20 \              # Time range (6 AM - 8 PM)
    -a BA KL \             # Airlines (British Airways, KLM)
    -s BUSINESS \          # Seat type
    -x NON_STOP \          # Non-stop flights only
    -o DURATION            # Sort by duration
```

### Find Cheapest Dates

```bash
# Basic search for cheapest dates
fli cheap JFK LHR

# Advanced search with date range
fli cheap JFK LHR \
    --from 2025-01-01 \
    --to 2025-02-01 \
    --monday --friday      # Only Mondays and Fridays
```

### CLI Options

#### Search Command (`fli search`)

| Option           | Description             | Example                |
|------------------|-------------------------|------------------------|
| `-t, --time`     | Time range (24h format) | `6-20`                 |
| `-a, --airlines` | Airline codes           | `BA KL`                |
| `-s, --seat`     | Cabin class             | `ECONOMY`, `BUSINESS`  |
| `-x, --stops`    | Maximum stops           | `NON_STOP`, `ONE_STOP` |
| `-o, --sort`     | Sort results by         | `CHEAPEST`, `DURATION` |

#### Cheap Command (`fli cheap`)

| Option        | Description   | Example                |
|---------------|---------------|------------------------|
| `--from`      | Start date    | `2025-01-01`           |
| `--to`        | End date      | `2025-02-01`           |
| `-s, --seat`  | Cabin class   | `ECONOMY`, `BUSINESS`  |
| `-x, --stops` | Maximum stops | `NON_STOP`, `ONE_STOP` |
| `--[day]`     | Day filters   | `--monday`, `--friday` |

## Python API Usage

### Basic Search Example

```python
from datetime import datetime, timedelta
from fli.models import Airport, PassengerInfo, SeatType, MaxStops, SortBy
from fli.search import SearchFlights, SearchFlightsFilters

# Create search filters
filters = SearchFlightsFilters(
    departure_airport=Airport.JFK,
    arrival_airport=Airport.LAX,
    departure_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
    passenger_info=PassengerInfo(adults=1),
    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}")
```

## Development

```bash
# Clone the repository
git clone https://github.com/punitarani/fli.git
cd fli

# Install dependencies with Poetry
poetry install

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .
poetry run ruff format .

# Build documentation
poetry run mkdocs serve
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License — see the LICENSE file for details.

