Installation Guide

Installation Guide

Prerequisites

• Python 3.10 or higher
• pip package manager
• A free WAQI API token — register at waqi.info
• Internet connection for live AQI data
• Jupyter Notebook (for generating model files on first run)

Step 1 — Extract and Enter the Project Folder

Unzip the downloaded project and open a terminal inside the extracted directory.

cd ClearSky-AI-AQI-Prediction

Step 2 — Create a Virtual Environment

python -m venv venv

Activate it:

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

Step 3 — Install All Dependencies

pip install -r requirements.txt

This installs Flask, XGBoost, scikit-learn, pandas, NumPy, joblib, and everything else the project needs.

Step 4 — Add Your WAQI API Token

Open app.py in any text editor. Near the top of the file, replace the placeholder value:

WAQI_TOKEN = "your_token_here"

Get a free token by signing up at the World Air Quality Index project website (waqi.info/api/).

Step 5 — Generate the Machine Learning Model Files

The three model artifact files — aqi_model.pkl, scaler.pkl, and feature_names.pkl — are generated by the Jupyter Notebook and must exist before the Flask app starts. If they are not already present in the project root, run:

pip install jupyter
jupyter notebook AQI_Prediction.ipynb

Inside Jupyter, go to the Kernel menu and click Restart and Run All. Wait for all ten cells to complete. The three .pkl files will appear in the project root once the notebook finishes.

Step 6 — Start the Flask Server

python app.py

You should see output similar to:

* Running on http://127.0.0.1:5001
* [startup] Model loaded. Features: ['PM2.5', 'PM10', ...]

The SQLite database file (aqi_history.db) is created automatically on the first run.

Step 7 — Open in Your Browser

• Dashboard: http://127.0.0.1:5001/
• Manual Prediction: http://127.0.0.1:5001/predict
• About: http://127.0.0.1:5001/about

Common Issues

• FileNotFoundError: aqi_model.pkl — The model files have not been generated yet. Run all cells in AQI_Prediction.ipynb first.
• Port 5001 already in use — Run lsof -i :5001 on Mac/Linux to find the process ID, then kill -9 <PID>. On Windows, use Task Manager to end the conflicting process.
• City not found or API error — Check the city name spelling or try a nearby major city. Coordinates also work: search geo:12.97;77.59 for Bangalore.
• ModuleNotFoundError — Your virtual environment is not activated. Run the activate command from Step 2 before installing dependencies.
• Weather tab shows "Weather data unavailable" — The WAQI monitoring station for that city does not report weather readings. Try Delhi or Mumbai, which have more complete station instrumentation.