Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

Update docs for v0.8.0 (#87)

Punit Arani0d592dd11dc0
diff --git a/AGENTS.md b/AGENTS.md
index 425829c..625bb8b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@ All standard commands are in the `Makefile` and `CLAUDE.md`. Key ones:
- **Format**: `make format`
- **Tests**: `make test` (standard), `make test-all` (including fuzz)
- **CLI**: `uv run fli flights JFK LAX 2026-05-15`
-- **MCP HTTP server**: `uv run fli-mcp-http` (serves at `http://127.0.0.1:8000/mcp`)
+- **MCP HTTP server**: `uv run fli-mcp-http` (serves at `http://127.0.0.1:8000/mcp/`)
### Testing caveats
@@ -26,4 +26,4 @@ All standard commands are in the `Makefile` and `CLAUDE.md`. Key ones:
### MCP server notes
- The MCP HTTP endpoint requires `Accept: application/json, text/event-stream` header.
-- The `fli/server/` module referenced in the Makefile (`make server`) does not exist yet; do not attempt to run it.
+- The `fli/server/` module has been removed from the codebase.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3eac206..3942849 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,7 +11,6 @@ Fli is a Python library that provides programmatic access to Google Flights data
- **Core utilities** (`fli/core/`) - Shared parsing and building utilities
- **Search engine** (`fli/search/`) - Flight and date search implementations using Google Flights API
- **Data models** (`fli/models/`) - Pydantic models for airports, airlines, and flight data structures
-- **FastAPI server** (`fli/server/`) - REST API endpoints for flight search functionality
## Development Commands
diff --git a/Makefile b/Makefile
index de1c292..2c2ec50 100644
--- a/Makefile
+++ b/Makefile
@@ -13,12 +13,6 @@ install-dev:
install-all:
uv sync --extra dev
-# Run the server
-server:
- uv run uvicorn fli.server.main:app
-server-dev:
- uv run uvicorn fli.server.main:app --reload
-
# Run the MCP server
mcp:
uv run fli-mcp
@@ -75,8 +69,6 @@ help:
@echo " make install - Install dependencies"
@echo " make install-dev - Install with dev dependencies"
@echo " make install-all - Install all dependencies"
- @echo " make server - Run the server"
- @echo " make server-dev - Run the development server with reload"
@echo " make mcp - Run the MCP server"
@echo " make docs - Build the docs"
@echo " make format - Format code using ruff"
@@ -91,4 +83,4 @@ help:
@echo " make devcontainer - Build dev container image"
@echo " make requirements - Generate the requirements.txt file"
# Declare the targets as phony
-.PHONY: help install install-dev install-all server server-dev mcp docs format lint lint-fix test test-mcp test-fuzz test-all ci ci-docker devcontainer requirements
+.PHONY: help install install-dev install-all mcp docs format lint lint-fix test test-mcp test-fuzz test-all ci ci-docker devcontainer requirements
diff --git a/README.md b/README.md
index 46bcc98..2e83c44 100644
--- a/README.md
+++ b/README.md
@@ -133,10 +133,10 @@ fli --help
```bash
# Basic flight search
-fli flights JFK LHR 2025-10-25
+fli flights JFK LHR 2026-10-25
# Advanced search with filters
-fli flights JFK LHR 2025-10-25 \
+fli flights JFK LHR 2026-10-25 \
--time 6-20 \ # Departure time window (6 AM - 8 PM)
--airlines BA KL \ # Airlines (British Airways, KLM)
--class BUSINESS \ # Cabin class
@@ -149,7 +149,7 @@ fli flights JFK LHR 2025-10-25 \
>
> ```bash
> # Return machine-readable flight results
-> fli flights JFK LHR 2025-10-25 --format json
+> fli flights JFK LHR 2026-10-25 --format json
> ```
### Find Cheapest Dates
@@ -160,8 +160,8 @@ fli dates JFK LHR
# Advanced search with date range
fli dates JFK LHR \
- --from 2025-01-01 \
- --to 2025-02-01 \
+ --from 2026-01-01 \
+ --to 2026-02-01 \
--monday --friday # Only Mondays and Fridays
```
@@ -170,7 +170,7 @@ fli dates JFK LHR \
>
> ```bash
> # Return machine-readable date search results
-> fli dates JFK LHR --from 2025-01-01 --to 2025-02-01 --format json
+> fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json
> ```
### CLI Options
@@ -179,6 +179,7 @@ fli dates JFK LHR \
| Option | Description | Example |
|------------------|-----------------------|------------------------|
+| `--return, -r` | Return date | `2026-10-30` |
| `--time, -t` | Departure time window | `6-20` |
| `--airlines, -a` | Airline IATA codes | `BA KL` |
| `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
@@ -188,14 +189,19 @@ fli dates JFK LHR \
#### Dates Command (`fli dates`)
-| Option | Description | Example |
-|---------------|---------------|------------------------|
-| `--from` | Start date | `2025-01-01` |
-| `--to` | End date | `2025-02-01` |
-| `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
-| `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |
-| `--[day]` | Day filters | `--monday`, `--friday` |
-| `--format` | Output format | `text`, `json` |
+| Option | Description | Example |
+|--------------------|------------------------|------------------------|
+| `--from` | Start date | `2026-01-01` |
+| `--to` | End date | `2026-02-01` |
+| `--duration, -d` | Trip duration in days | `3` |
+| `--round, -R` | Round-trip search | (flag) |
+| `--airlines, -a` | Airline IATA codes | `BA KL` |
+| `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |
+| `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |
+| `--time` | Departure time window | `6-20` |
+| `--sort` | Sort by price | (flag) |
+| `--[day]` | Day filters | `--monday`, `--friday` |
+| `--format` | Output format | `text`, `json` |
## MCP Server Integration
diff --git a/docs/api/models.md b/docs/api/models.md
index e786a51..d026b3b 100644
--- a/docs/api/models.md
+++ b/docs/api/models.md
@@ -17,12 +17,12 @@ flight_segments = [
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
),
FlightSegment(
departure_airport=[[Airport.LAX, 0]],
arrival_airport=[[Airport.JFK, 0]],
- travel_date="2024-06-15",
+ travel_date="2026-06-15",
)
]
diff --git a/docs/api/search.md b/docs/api/search.md
index ad560dd..9aafce6 100644
--- a/docs/api/search.md
+++ b/docs/api/search.md
@@ -41,7 +41,7 @@ filters = FlightSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
)
],
seat_type=SeatType.ECONOMY
@@ -65,11 +65,11 @@ filters = DateSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
)
],
- from_date="2024-06-01",
- to_date="2024-06-30"
+ from_date="2026-06-01",
+ to_date="2026-06-30"
)
# Search dates
diff --git a/docs/examples/advanced.md b/docs/examples/advanced.md
index c2ab6f9..cc26acf 100644
--- a/docs/examples/advanced.md
+++ b/docs/examples/advanced.md
@@ -41,7 +41,7 @@ filters = FlightSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LHR, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
)
],
seat_type=SeatType.BUSINESS,
@@ -75,7 +75,7 @@ filters = FlightSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
time_restrictions=TimeRestrictions(
earliest_departure=6, # 6 AM
latest_departure=10, # 10 AM
@@ -110,11 +110,11 @@ filters = DateSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
)
],
- from_date="2024-06-01",
- to_date="2024-06-30",
+ from_date="2026-06-01",
+ to_date="2026-06-30",
seat_type=SeatType.PREMIUM_ECONOMY
)
@@ -145,11 +145,11 @@ def track_prices(days=7):
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
)
],
- from_date="2024-06-01",
- to_date="2024-06-07"
+ from_date="2026-06-01",
+ to_date="2026-06-07"
)
search = SearchDates()
@@ -232,7 +232,7 @@ def analyze_results(results: List[FlightResult]) -> pd.DataFrame:
from fli.models import (
Airport, Airline, SeatType, MaxStops,
PassengerInfo, TimeRestrictions, TripType,
- FlightSegment, FlightSearchFilters
+ FlightSegment, FlightSearchFilters, LayoverRestrictions
)
from fli.search import SearchFlights
from datetime import datetime, timedelta
@@ -241,7 +241,7 @@ from datetime import datetime, timedelta
outbound = FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LHR, 0]],
- travel_date="2024-06-01",
+ travel_date="2026-06-01",
time_restrictions=TimeRestrictions(
earliest_departure=6, # 6 AM
latest_departure=12, # 12 PM
@@ -253,7 +253,7 @@ outbound = FlightSegment(
return_flight = FlightSegment(
departure_airport=[[Airport.LHR, 0]],
arrival_airport=[[Airport.JFK, 0]],
- travel_date="2024-06-15",
+ travel_date="2026-06-15",
time_restrictions=TimeRestrictions(
earliest_departure=14, # 2 PM
latest_departure=20, # 8 PM
@@ -296,27 +296,20 @@ filters = FlightSearchFilters(
search = SearchFlights()
results = search.search(filters)
-# Process results with detailed information
-for flight in results:
- print(f"\nTotal Price: ${flight.total_price}")
-
- print("\nOutbound Flight:")
- for leg in flight.outbound.legs:
- print(f"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}")
- print(f"Duration: {leg.duration} minutes")
- if leg.layover_duration:
- print(f"Layover: {leg.layover_duration} minutes")
-
- print("\nReturn Flight:")
- for leg in flight.return_flight.legs:
- print(f"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}")
- print(f"Duration: {leg.duration} minutes")
- if leg.layover_duration:
- print(f"Layover: {leg.layover_duration} minutes")
+for outbound_result, return_result in results:
+ print(f"\nOutbound Flight (${outbound_result.price}):")
+ for leg in outbound_result.legs:
+ print(f" 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}")
+ print(f" Duration: {leg.duration} minutes")
+
+ print(f"\nReturn Flight:")
+ for leg in return_result.legs:
+ print(f" 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}")
+ print(f" Duration: {leg.duration} minutes")
```
### Advanced Date Search with Validation
@@ -350,8 +343,8 @@ def validate_dates(from_date: str, to_date: str, min_stay: int, max_stay: int):
raise ValueError("Minimum stay cannot be greater than maximum stay")
-from_date = "2024-06-01"
-to_date = "2024-06-30"
+from_date = "2026-06-01"
+to_date = "2026-06-30"
min_stay = 2
max_stay = 4
diff --git a/docs/guides/mcp.md b/docs/guides/mcp.md
index 2da0c78..27857de 100644
--- a/docs/guides/mcp.md
+++ b/docs/guides/mcp.md
@@ -92,8 +92,8 @@ Search for flights between two airports on a specific date.
{
"departure_airport": "JFK",
"arrival_airport": "LHR",
- "departure_time": "2025-03-15T18:00:00",
- "arrival_time": "2025-03-16T06:30:00",
+ "departure_time": "2026-03-15T18:00:00",
+ "arrival_time": "2026-03-16T06:30:00",
"duration": 450,
"airline": "BA",
"flight_number": "BA178"
@@ -134,13 +134,13 @@ Find the cheapest travel dates between two airports within a date range.
"success": true,
"dates": [
{
- "date": "2025-03-15",
+ "date": "2026-03-15",
"price": 350.00,
"currency": "USD",
"return_date": null
},
{
- "date": "2025-03-18",
+ "date": "2026-03-18",
"price": 375.00,
"currency": "USD",
"return_date": null
@@ -148,7 +148,7 @@ Find the cheapest travel dates between two airports within a date range.
],
"count": 30,
"trip_type": "ONE_WAY",
- "date_range": "2025-03-01 to 2025-03-31"
+ "date_range": "2026-03-01 to 2026-03-31"
}
```
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
index 7da7bac..4b67f15 100644
--- a/docs/guides/quickstart.md
+++ b/docs/guides/quickstart.md
@@ -23,19 +23,19 @@ pipx install flights
1. Search for one-way flights:
```bash
-fli flights JFK LHR 2025-06-01
+fli flights JFK LHR 2026-06-01
```
2. Search for round trip flights:
```bash
-fli flights JFK LHR 2025-06-01 --return 2025-06-15
+fli flights JFK LHR 2026-06-01 --return 2026-06-15
```
3. Search with filters:
```bash
-fli flights JFK LHR 2025-06-01 \
+fli flights JFK LHR 2026-06-01 \
--time 6-20 \ # Departure window (6 AM - 8 PM)
--airlines BA KL \ # Airlines (British Airways, KLM)
--class BUSINESS \ # Cabin class
@@ -45,7 +45,7 @@ fli flights JFK LHR 2025-06-01 \
4. Find cheapest dates:
```bash
-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30
+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30
```
!!! warning "Experimental"
@@ -55,8 +55,8 @@ fli dates JFK LHR --from 2025-06-01 --to 2025-06-30
5. Return machine-readable JSON:
```bash
-fli flights JFK LHR 2025-06-01 --format json
-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30 --format json
+fli flights JFK LHR 2026-06-01 --format json
+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30 --format json
```
### MCP Server (for AI Assistants)
@@ -89,7 +89,7 @@ flight_segments = [
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2025-06-01"
+ travel_date="2026-06-01"
)
]
@@ -127,12 +127,12 @@ flight_segments = [
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2025-06-01"
+ travel_date="2026-06-01"
),
FlightSegment(
departure_airport=[[Airport.LAX, 0]],
arrival_airport=[[Airport.JFK, 0]],
- travel_date="2025-06-15"
+ travel_date="2026-06-15"
)
]
@@ -175,11 +175,11 @@ filters = DateSearchFilters(
FlightSegment(
departure_airport=[[Airport.JFK, 0]],
arrival_airport=[[Airport.LAX, 0]],
- travel_date="2025-06-01",
+ travel_date="2026-06-01",
)
],
- from_date="2025-06-01",
- to_date="2025-06-30"
+ from_date="2026-06-01",
+ to_date="2026-06-30"
)
# Search dates
@@ -212,7 +212,13 @@ python examples/basic_one_way_search.py
* `round_trip_search.py` - Round-trip flight search example
* `date_range_search.py` - Date range search example
* `complex_flight_search.py` - Advanced filtering example
+* `time_restrictions_search.py` - Time-constrained search example
+* `date_search_with_preferences.py` - Weekend and day filtering example
+* `complex_round_trip_validation.py` - Complex round-trip with validation
+* `advanced_date_search_validation.py` - Advanced date search with validation
+* `price_tracking.py` - Price monitoring over time
* `error_handling_with_retries.py` - Robust error handling example
+* `result_processing.py` - Data analysis with pandas
> 💡 **Tip**: Examples include automatic dependency checking and will guide you through installation if dependencies are missing.
diff --git a/docs/index.md b/docs/index.md
index 37a65c6..60b2e34 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -69,8 +69,8 @@ See the [MCP Guide](guides/mcp.md) for Claude Desktop configuration.
The `--format json` CLI output is experimental. The schema is intended for agents and tools such as `jq`, but may evolve in future releases.
```bash
-fli flights JFK LHR 2025-06-01 --format json
-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30 --format json
+fli flights JFK LHR 2026-06-01 --format json
+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30 --format json
```
```python
diff --git a/examples/README.md b/examples/README.md
index 0483c89..a8bb6ba 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -198,8 +198,8 @@ from datetime import datetime, timedelta
future_date = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")
# Date ranges
-from_date = "2024-06-01"
-to_date = "2024-06-30"
+from_date = "2026-06-01"
+to_date = "2026-06-30"
```
### Passenger Configuration
diff --git a/mkdocs.yml b/mkdocs.yml
index 86c3adf..265979a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,9 +1,9 @@
site_name: Fli Documentation
site_url: https://punitarani.github.io/fli
-site_description: Documentation for the Fli library - A Python wrapper for Google Flights API
+site_description: Documentation for the Fli library - A Python library for direct Google Flights API access
repo_url: https://github.com/punitarani/fli
site_author: Punit Arani
-copyright: Copyright © 2024 Punit Arani
+copyright: Copyright © 2024-2026 Punit Arani
theme:
name: material
diff --git a/skills/fli/SKILL.md b/skills/fli/SKILL.md
index 2a7527b..13cb79d 100644
--- a/skills/fli/SKILL.md
+++ b/skills/fli/SKILL.md
@@ -105,7 +105,7 @@ Do not tell users to run `pipx install fli`.
Use:
```bash
-fli flights JFK LAX 2025-10-25
+fli flights JFK LAX 2026-10-25
```
### Cheapest-date search
@@ -113,7 +113,7 @@ fli flights JFK LAX 2025-10-25
Use:
```bash
-fli dates JFK LAX --from 2025-01-01 --to 2025-01-31
+fli dates JFK LAX --from 2026-01-01 --to 2026-01-31
```
### Common filters
@@ -121,7 +121,7 @@ fli dates JFK LAX --from 2025-01-01 --to 2025-01-31
Use filters like these when the user asks for them:
```bash
-fli flights JFK LHR 2025-10-25 \
+fli flights JFK LHR 2026-10-25 \
--time 6-20 \
--airlines BA KL \
--class BUSINESS \