marwa698/egypt-real-estate-predictor

# 🏠 Egypt Real Estate Price Predictor > An intelligent full-stack ML system that predicts real estate prices across Egypt based on 19,000+ real market listings — with SHAP explainability, FastAPI backend, and a bilingual React frontend. --- ## 📸 Screenshots ### Light Mode (Arabic) ### Dark Mode (English) ### SHAP Explainability ### API Documentation --- ## 🎯 What Makes This Project Different Most real estate price predictors just give you a number. This system: - ✅ **Explains WHY** — SHAP values show which factors (location, size, type) drove the prediction - ✅ **Real Market Data** — 19,321 cleaned listings from Property Finder Egypt - ✅ **Price Range** — not just one number, but a confidence interval - ✅ **Market Comparison** — compare your property vs. area average price/m² - ✅ **Bilingual UI** — full Arabic (RTL) and English (LTR) support - ✅ **Dark / Light Mode** — persisted across sessions --- ## 🧱 Tech Stack | Layer | Technology | |---|---| | Data | 19,321 real listings from Property Finder Egypt | | ML Model | XGBoost (R² = 0.74, MAE ≈ 4.9M EGP) | | Hyperparameter Tuning | Optuna (50 trials) | | Explainability | SHAP via XGBoost native `pred_contribs` | | Backend | FastAPI + Uvicorn | | Frontend | React + Vite | | Styling | CSS3 with CSS Variables (Dark/Light themes) | | Language | Arabic/English toggle with RTL/LTR support | --- ## 📊 Model Performance | Metric | Value | |---|---| | R² Score | **0.74** | | MAE | **~4.9M EGP** | | Training samples | 15,456 | | Test samples | 3,865 | | Hyperparameter tuning | Optuna (50 trials, 3-fold CV) | **Top features by SHAP importance:** 1. Area price per m² (target-encoded) — 36.8% 2. Property type — 20.4% 3. Size (m²) — 11.1% --- ## 🚀 API Endpoints ``` GET /health → Health check GET /areas → List of governorates, areas, property types POST /predict → Predict price with confidence range POST /explain → SHAP explanation of prediction GET /market-anal …