Skip to content

README_GITHUB.md

Latest commit

 

History

History
408 lines (294 loc) · 11.9 KB

README_GITHUB.md

File metadata and controls

408 lines (294 loc) · 11.9 KB

✈️ Flight Price Monitor Multi-Country

Version Python License Platform

Compare flight prices across different countries and save up to 30% on your tickets!

Features • Demo • Installation • Usage • Documentation • Contributing

🎯 What is this?

A smart flight price monitoring system that simulates purchases from different countries using VPN, searches across 5 major travel sites, and automatically converts all prices to your local currency (BRL). Perfect for finding the best deals on international flights!

💡 Why does this work?

Airlines and travel sites often show different prices based on your location. By checking prices from multiple countries, you can find significantly cheaper tickets - sometimes saving hundreds of dollars on the same flight!

✨ Features

🔥 Version 3.0 Highlights

  • ✈️ Animated UI - Beautiful plane animation during search
  • 🔒 VPN Integration - Automatic VPN switching per country (NordVPN support)
  • 🌐 5 Travel Sites - Google Flights, Kayak, Skyscanner, Decolar, Momondo
  • 💰 Auto Currency Conversion - Real-time exchange rates with 1-hour cache
  • 📊 Smart Comparison - Automatic ranking and savings calculation
  • 🎯 Real Web Scrapers - Playwright + BeautifulSoup for actual price data
  • 🔄 Auto-restart - Systemd service with automatic recovery
  • 📱 Responsive Design - Works on desktop, tablet, and mobile
  • 📝 Detailed Logging - Full audit trail of all searches
  • 🚀 Background Service - Runs 24/7 with systemd integration

🖼️ Demo

Search Interface

┌────────────────────────────────────────────────┐
│  ✈️ Flight Monitor Multi-Country V3.0          │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│  ✈️ Animated  🔒 VPN     🌐 5 Sites           │
│  Plane       Per Country  +Momondo!           │
│                                                │
│  Origin: GRU  →  Destination: LIS             │
│  Dates: 15/12 → 22/12                         │
│                                                │
│  Countries: 🇧🇷 Brazil  🇺🇸 USA  🇵🇹 Portugal │
│                                                │
│  [🚀 SEARCH BEST PRICES]                      │
└────────────────────────────────────────────────┘

Results

🏆 BEST PRICE FOUND: R$ 2,440.80
   From Portugal 🇵🇹
   💰 Save R$ 449.20 (15.5%)

┌────────────────────────────────────────────────┐
│ 🥇 🇵🇹 PORTUGAL                                │
│ EUR 452.00 → R$ 2,440.80                       │
│ 🌐 Kayak | ✈️ GRU→LIS | 🔒 VPN: ON            │
└────────────────────────────────────────────────┘

┌────────────────────────────────────────────────┐
│ 🥈 🇺🇸 USA                   (+3%)             │
│ USD 505.00 → R$ 2,525.00                       │
│ 🌐 Google Flights | ✈️ GRU→LIS                │
└────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

  • Python 3.8+
  • Raspberry Pi / Linux server (or any Unix-like system)
  • 512MB RAM minimum
  • Internet connection

Installation (3 commands)

# 1. Clone repository
git clone https://github.com/yourusername/flight-price-monitor.git
cd flight-price-monitor

# 2. Install dependencies & configure service
chmod +x install_raspberry.sh setup_service.sh
sudo ./install_raspberry.sh
sudo ./setup_service.sh

# 3. Access application
# Open browser: http://localhost:8776

That's it! The service now runs 24/7 and starts automatically on boot! 🎉

📦 Installation

Detailed Installation

Step 1: System Dependencies

sudo apt-get update
sudo apt-get install -y \
    libxml2-dev \
    libxslt-dev \
    python3-dev \
    build-essential \
    libssl-dev \
    libffi-dev

Step 2: Python Packages

pip3 install --break-system-packages \
    Flask \
    requests \
    beautifulsoup4 \
    html5lib \
    python-dateutil \
    PySocks

Step 3: Optional - Playwright (for advanced scrapers)

pip3 install --break-system-packages playwright
playwright install chromium

Step 4: Run Application

# Manual run
python3 app_v3_COMPLETO.py

# Or install as service (recommended)
sudo ./setup_service.sh

🎮 Usage

Basic Search

  1. Access http://localhost:8776 in your browser
  2. Enter origin (e.g., GRU) and destination (e.g., LIS)
  3. Select dates
  4. Choose 3-5 countries to compare
  5. Click "SEARCH BEST PRICES"
  6. Wait 30-90 seconds for results
  7. Compare prices and save money! 💰

Service Management

Using Interactive Menu (Easy)

./manage_service.sh

Using Commands

# Check status
sudo systemctl status flight-monitor

# Restart
sudo systemctl restart flight-monitor

# View logs
sudo journalctl -u flight-monitor -f

# Stop
sudo systemctl stop flight-monitor

🌍 Supported Countries (18)

🇧🇷 Brazil | 🇺🇸 USA | 🇵🇹 Portugal | 🇪🇸 Spain | 🇬🇧 UK | 🇩🇪 Germany
🇫🇷 France | 🇨🇦 Canada | 🇦🇷 Argentina | 🇨🇱 Chile | 🇲🇽 Mexico
🇮🇹 Italy | 🇳🇱 Netherlands | 🇮🇪 Ireland | 🇨🇭 Switzerland | 🇯🇵 Japan
🇦🇺 Australia | 🇹🇷 Turkey

More can be easily added in COUNTRY_MAP!

🔧 Configuration

VPN Setup (Optional but Recommended)

For real VPN functionality:

  1. Install NordVPN via Docker
  2. Edit app_v3_COMPLETO.py line ~101
  3. Uncomment VPN connection code
# Uncomment these lines:
result = subprocess.run([
    'docker', 'exec', 'nordvpn_flight',
    'nordvpn', 'c', vpn_name
], capture_output=True, text=True, timeout=30)

Change Port

# Edit app
nano app_v3_COMPLETO.py

# Change line (end of file):
port = int(os.environ.get('FLASK_PORT', 8776))  # Change 8776 to desired port

Add More Countries

Edit COUNTRY_MAP in app_v3_COMPLETO.py:

'new_country': {
    'name': 'Country Name',
    'flag': '🏴',
    'currency': 'USD',
    'vpn': 'VPN_Server_Name'
}

📊 Performance

Scenario Time Results
1 country ~15s 5 prices
3 countries ~45s 15 prices
5 countries ~75s 25 prices

Raspberry Pi 4 (4GB):

  • ✅ Runs perfectly
  • 💾 RAM usage: ~150MB
  • ⚡ Fast response times

📚 Documentation

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                  Web Interface                      │
│              (HTML + CSS + JS)                      │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────┐
│              Flask API (Python)                     │
│  • Search endpoint                                  │
│  • Results endpoint                                 │
│  • Health check                                     │
└────────────────┬────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
┌───────▼──────┐  ┌──────▼───────┐
│ VPN Manager  │  │  Exchange    │
│  (NordVPN)   │  │  Rate API    │
└───────┬──────┘  └──────────────┘
        │
┌───────▼─────────────────────────────────────────────┐
│              Web Scrapers                           │
│  • Playwright (Google Flights)                      │
│  • BeautifulSoup (Kayak, Decolar, Momondo)          │
└─────────────────────────────────────────────────────┘

🛠️ Tech Stack

  • Backend: Flask (Python 3.8+)
  • Web Scraping: Playwright, BeautifulSoup4
  • VPN: NordVPN (Docker)
  • Currency API: AwesomeAPI
  • Frontend: Vanilla JavaScript, HTML5, CSS3
  • Service: systemd
  • Platform: Linux (optimized for Raspberry Pi)

🤝 Contributing

Contributions are welcome! Here's how you can help:

Areas for Improvement

  • Improve scraper success rate
  • Add more travel sites
  • Implement price history tracking
  • Add email/Telegram notifications
  • Create mobile app
  • Add ML price prediction
  • Support for hotels and car rentals

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

🐛 Known Issues

  • Scrapers may fail due to anti-bot protections (fallback to simulated data)
  • Playwright requires ~500MB disk space for browser
  • VPN requires NordVPN subscription and Docker setup
  • Rate limiting may occur with frequent searches

See Issues for known bugs and planned features.

📝 License

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

👏 Acknowledgments

  • Inspired by the need to find better flight deals
  • Built with love for travelers on a budget
  • Thanks to all contributors and users!

📞 Support

🌟 Star History

If this project helped you save money on flights, consider giving it a star! ⭐

📈 Roadmap

Version 3.1 (Next)

  • Email notifications
  • Price history graphs
  • More countries (target: 30)
  • Better error handling

Version 4.0 (Future)

  • Mobile app (React Native)
  • Price prediction ML model
  • Hotel comparison
  • API for third-party integration

Made with ❤️ by travelers, for travelers

⬆ Back to top