A REST API server for searching flights using Google Flights data, powered by fast-flights and FastAPI.

# Install Python 3.11
pyenv install 3.11.9
pyenv local 3.11.9

# Create virtual environment
$(pyenv which python) -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Option 1: Run directly
python main.py

# Option 2: Run with uvicorn (with hot reload)
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The server will start at http://localhost:8000

A single-page HTML UI is included for testing the API. Simply open test_ui.html in your browser:

# Open the HTML file in your default browser
open test_ui.html  # macOS
# or
xdg-open test_ui.html  # Linux
# or just double-click test_ui.html

The UI includes:

• Flight Search: Search for flights with an intuitive form
• Airport Search: Find airports by name or city
• Results Display: Beautiful, easy-to-read flight results

Note: Make sure the API server is running on http://localhost:8000 for the UI to work.

FastAPI provides built-in interactive documentation:

Check if the service is running.

Request:

GET /api/health

Response:

{
  "status": "ok"
}

Example:

curl http://localhost:8000/api/health

Search for airports by name or city.

Request:

GET /api/airports/search?q={query}

Query Parameters:

Response:

{
  "airports": [
    {
      "code": "TPE",
      "name": "TAIWAN_TAOYUAN_INTERNATIONAL_AIRPORT"
    },
    {
      "code": "TSA",
      "name": "TAIPEI_SONGSHAN_AIRPORT"
    }
  ]
}

Examples:

# Search for airports in Taipei
curl "http://localhost:8000/api/airports/search?q=taipei"

# Search for airports in Los Angeles
curl "http://localhost:8000/api/airports/search?q=angeles"

# Search for airports in Kayseri
curl "http://localhost:8000/api/airports/search?q=kayseri"

Search for available flights based on criteria.

Request:

POST /api/flights/search
Content-Type: application/json

Request Body:

{
  "from_airport": "TPE",
  "to_airport": "LAX",
  "date": "2025-02-01",
  "return_date": null,
  "trip": "one-way",
  "airlines": ["DL", "AA"],
  "max_stops": 2,
  "seat": "economy",
  "passengers": {
    "adults": 1,
    "children": 0,
    "infants_in_seat": 0,
    "infants_on_lap": 0
  }
}

Request Body Parameters:

Constraints:

• Total passengers cannot exceed 9
• Number of infants on lap cannot exceed number of adults
• One-way trips: return_date must be null or omitted
• Round-trip: return_date is required
• Single-leg searches only (A→B for one-way, A→B→A for round-trip)

Fetch Modes:

• common (default) - Standard web scraping using HTTP requests, fast and lightweight
• local - Uses local Playwright browser to render JavaScript (requires additional setup)

Valid Airlines Values:

• Any 2-letter IATA airline code (e.g., DL, AA, UA, BA)
• Alliance names: SKYTEAM, STAR_ALLIANCE, ONEWORLD

Response:

{
  "current_price": "low",
  "flights": [
    {
      "is_best": true,
      "name": "Delta",
      "departure": "2025-02-01 10:30 AM",
      "arrival": "2025-02-01 6:45 PM",
      "arrival_time_ahead": "+0",
      "duration": "12h 15m",
      "stops": 1,
      "delay": null,
      "price": "$542"
    }
  ]
}

Examples:

# One-way flight search
curl -X POST "http://localhost:8000/api/flights/search" \
  -H "Content-Type: application/json" \
  -d '{
    "from_airport": "JFK",
    "to_airport": "LAX",
    "date": "2026-02-06",
    "trip": "one-way",
    "seat": "economy",
    "passengers": {
      "adults": 1
    }
  }'

# Round-trip flight search
curl -X POST "http://localhost:8000/api/flights/search" \
  -H "Content-Type: application/json" \
  -d '{
    "from_airport": "JFK",
    "to_airport": "LAX",
    "date": "2026-02-06",
    "return_date": "2026-02-13",
    "trip": "round-trip",
    "seat": "economy",
    "passengers": {
      "adults": 2,
      "children": 1
    }
  }'

# Business class with max stops filter
curl -X POST "http://localhost:8000/api/flights/search" \
  -H "Content-Type: application/json" \
  -d '{
    "from_airport": "SFO",
    "to_airport": "NRT",
    "date": "2026-02-06",
    "trip": "one-way",
    "max_stops": 1,
    "seat": "business",
    "passengers": {
      "adults": 1
    }
  }'

# Family trip with multiple passengers
curl -X POST "http://localhost:8000/api/flights/search" \
  -H "Content-Type: application/json" \
  -d '{
    "from_airport": "JFK",
    "to_airport": "LAX",
    "date": "2026-02-06",
    "trip": "one-way",
    "seat": "economy",
    "passengers": {
      "adults": 2,
      "children": 2,
      "infants_in_seat": 0,
      "infants_on_lap": 0
    }
  }'

All endpoints return errors in this format:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes:

This API can be exposed via the Model Context Protocol (MCP) using gen-mcp, allowing AI assistants to interact with the flight search API directly.

1. Download gen-mcp:

   # Latest release version
   make download-genmcp-release
   
   # Or nightly snapshot
   make download-genmcp-nightly

2. Start the API server:

   python main.py

3. Fetch OpenAPI spec:

   make fetch-openapi
   # Or manually: curl http://localhost:8000/openapi.json > openapi.json

4. Generate MCP configuration:

   make generate-mcpfile

   This creates mcpfile.yaml from the OpenAPI spec with invocationBases configured.

   Configure API URL (optional, defaults to http://localhost:8000):

   API_URL=http://localhost:8000 make generate-mcpfile

5. Start MCP server:

   make start-mcp-server

6. Stop MCP server:

   make stop-mcp-server

The API server logs all requests, responses, and fast-flights library calls:

• API Server Logs: api-server.log (also output to stdout)
• MCP Server Logs: .genmcp/mcp-server.log

View logs:

# View recent logs
make view-logs

# Follow API server logs in real-time
tail -f api-server.log

What gets logged:

• All HTTP requests and responses (method, path, status, timing)
• Request/response bodies (for debugging)
• Fast-flights library calls (function calls, parameters)
• Google Flights HTTP requests (via httpx/httpcore logging)
• Errors with full stack traces

• .genmcp/ - Directory containing the gen-mcp binary (not checked in)
• mcpfile.yaml - MCP tool definitions generated from OpenAPI spec (not checked in)
• openapi.json - OpenAPI specification (not checked in)

MIT