Air_Quality_Detector

Air Quality Detector 🌍

🚀 Quick Start (TL;DR)

# 1. Get API key from https://www.iqair.com/dashboard/api
# 2. Install dependencies
pip install -r requirements.txt

# 3. Create .env file and add your API key
copy .env.example .env
# Edit .env and add: IQAIR_API_KEY=your_key_here

# 4. Run the app
python main.py

Description

A beginner-friendly Python application that shows you how polluted the air is in any city around the world! This project teaches you how to:

• Build a graphical user interface (GUI) with Tkinter
• Make API calls to get real-time data
• Process and display information beautifully
• Handle errors gracefully
• Use environment variables to keep API keys secure 🔐

Perfect for: Students learning Python, API integration, GUI development, and security best practices

What is AQI?

AQI (Air Quality Index) is a number that tells you how clean or polluted the air is:

• 0-50: 🟢 Good - Go outside and play!
• 51-100: 🟡 Moderate - Air is okay for most people
• 101-150: 🟠 Unhealthy for sensitive groups - Be careful if you have asthma
• 151-200: 🔴 Unhealthy - Everyone should limit outdoor time
• 201-300: 🟣 Very Unhealthy - Avoid going outside
• 301+: 🟤 Hazardous - Stay indoors!

Features

• 🌍 Real-time AQI data from IQAir API
• 📍 Auto-detect location based on IP
• 🎨 Color-coded AQI display (Good to Hazardous)
• 📊 Detailed pollutant info (PM2.5, PM10, O3, NO2, SO2, CO)
• 🌡️ Weather conditions (temperature, humidity, pressure, wind)
• 💡 Health recommendations based on AQI levels
• 🇺🇸🇨🇳 Dual AQI standards (US EPA & China MEP)
• 🕐 Last updated timestamp

Stack

• Language: Python
• Libraries:
  • tkinter (GUI)
  • requests==2.31.0 (API calls)
• API: IQAir API (free tier included)
• Complexity: Intermediate

Installation

Step 1: Get Your Free API Key

1. Visit IQAir Dashboard: Go to https://www.iqair.com/dashboard/api
2. Sign Up/Login:
   • Click "Get Started" or "Sign In"
   • Create a free account (use your email)
   • Verify your email address
3. Get API Key:
   • Once logged in, you'll see your dashboard
   • Look for "API Key" section
   • Copy your API key (it looks like: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Step 2: Set Up the Project

# 1. Install dependencies
pip install -r requirements.txt

# 2. Create .env file
# Copy the example file
copy .env.example .env

# 3. Add your API key to .env file
# Open .env in a text editor and replace 'your_api_key_here' with your actual API key
# Example:
# IQAIR_API_KEY=e6fa641d-6bc7-48db-94c8-f3f1e4a1a7ac

Step 3: Run the Application

python main.py

Important: Never share your .env file or commit it to GitHub! It contains your secret API key.

Usage

Method 1: Manual Entry

1. Enter City (e.g., "Beijing")
2. Enter State (e.g., "Beijing")
3. Enter Country (e.g., "China")
4. Click "🔍 Check AQI"

Method 2: Auto-Detect

1. Click "📍 Use My Location"
2. App auto-fills your location based on IP
3. Displays AQI instantly!

🔑 How to Get Your API Key (Detailed Guide)

Visual Step-by-Step Guide

Step 1: Visit IQAir Dashboard

🌐 URL: https://www.iqair.com/dashboard/api

Step 2: Create Account

┌─────────────────────────────────────┐
│   IQAir Air Quality API             │
├─────────────────────────────────────┤
│                                     │
│   [Get Started] or [Sign In]       │
│                                     │
│   Email: [email protected]    │
│   Password: ••••••••••             │
│                                     │
│   [ Create Account ]                │
│                                     │
└─────────────────────────────────────┘

Step 3: Verify Email

• Check your email inbox
• Click the verification link
• Return to IQAir dashboard

Step 4: Find Your API Key

┌─────────────────────────────────────┐
│   Dashboard                         │
├─────────────────────────────────────┤
│                                     │
│   📊 API Statistics                 │
│   ├─ Calls Today: 0/10,000         │
│   └─ Calls This Month: 0/10,000    │
│                                     │
│   🔑 Your API Key:                  │
│   ┌───────────────────────────────┐│
│   │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxx ││  ← Copy this!
│   └───────────────────────────────┘│
│   [Copy to Clipboard]               │
│                                     │
└─────────────────────────────────────┘

Step 5: Add to .env File

# Open .env file in any text editor (Notepad, VS Code, etc.)
# Replace 'your_api_key_here' with your actual key

# Before:
IQAIR_API_KEY=your_api_key_here

# After:
IQAIR_API_KEY=e6fa641d-6bc7-48db-94c8-f3f1e4a1a7ac

Free Tier Limits

• ✅ 10,000 calls per month
• ✅ Real-time data
• ✅ 30,000+ stations worldwide
• ✅ No credit card required

Security Best Practices

✅ DO:

• Keep your API key in .env file
• Add .env to .gitignore
• Never share your API key publicly

❌ DON'T:

• Commit .env to GitHub
• Share your API key in screenshots
• Hardcode API key in source code

AQI Categories

AQI Range	Category	Color	Health Impact
0-50	Good	🟢 Green	Satisfactory
51-100	Moderate	🟡 Yellow	Acceptable
101-150	Unhealthy for Sensitive Groups	🟠 Orange	Sensitive groups affected
151-200	Unhealthy	🔴 Red	Everyone affected
201-300	Very Unhealthy	🟣 Purple	Health alert
301+	Hazardous	🟤 Maroon	Emergency conditions

Example Locations

Try these cities:

• Beijing, Beijing, China
• Los Angeles, California, USA
• Delhi, Delhi, India
• London, England, United Kingdom
• Tokyo, Tokyo, Japan

Features Explained

Pollutant Details

• PM2.5: Fine particulate matter (< 2.5 micrometers)
• PM10: Coarse particulate matter (< 10 micrometers)
• O3: Ground-level ozone
• NO2: Nitrogen dioxide
• SO2: Sulfur dioxide
• CO: Carbon monoxide

Weather Integration

• Real-time temperature, humidity, pressure
• Wind speed and direction
• Synchronized with pollution data

📚 How the Code Works (For Students)

1. Imports & Environment Variables (Lines 16-25)

import tkinter as tk       # Creates windows, buttons, labels
import requests            # Makes API calls to get data from internet
import os                  # Access environment variables
from dotenv import load_dotenv  # Load .env file

load_dotenv()  # This reads the .env file

What are Environment Variables?

• Special variables stored outside your code
• Used for sensitive data (like API keys, passwords)
• Keeps secrets safe and not visible in code
• Each developer can have their own .env file

Why use .env files?

• ✅ Security: API keys not in source code
• ✅ Flexibility: Easy to change without editing code
• ✅ Safety: .env is in .gitignore (won't upload to GitHub)
• ✅ Best Practice: Industry standard for managing secrets

2. Class Structure

The entire app is organized in a class called AirQualityApp. Think of a class as a blueprint:

• __init__(): Runs when app starts (sets up window, API key)
• create_widgets(): Creates all buttons, labels, input boxes
• check_aqi(): Gets air quality data when you click "Check AQI"
• display_aqi_data(): Shows the results on screen

3. API Calls (How we get data)

# We send a request to IQAir's server
response = requests.get(url, params=params)

# They send back data in JSON format
data = response.json()

# We extract what we need
aqi = data['current']['pollution']['aqius']

4. GUI Layout

┌─────────────────────────────────┐
│    🌍 Air Quality Detector      │  ← Title Label
├─────────────────────────────────┤
│  City:    [________]            │  ← Input Fields
│  State:   [________]            │
│  Country: [________]            │
│  [🔍 Check AQI] [📍 My Location]│  ← Buttons
├─────────────────────────────────┤
│         157                     │  ← Big AQI Number
│    🏷️ Unhealthy                 │  ← Category
│  📍 Los Angeles, CA, USA        │  ← Location
│  [Detailed Information Box]     │  ← Text Widget
└─────────────────────────────────┘

5. Error Handling

The code uses try-except blocks to handle problems:

• Timeout: Internet too slow
• ConnectionError: No internet
• Empty fields: User didn't enter city/state/country

6. Color Coding

if aqi <= 50:
    color = "#4caf50"  # Green (Good)
elif aqi <= 100:
    color = "#ffeb3b"  # Yellow (Moderate)
# ... and so on

🎓 What You'll Learn

1. GUI Programming: How to create windows, buttons, and labels with Tkinter
2. API Integration: How to get real-time data from the internet
3. Environment Variables: How to keep API keys secure using .env files
4. Data Processing: How to extract and format JSON data
5. Error Handling: How to deal with problems gracefully (try-except)
6. Security Best Practices: Never hardcode secrets in source code
7. User Experience: How to make apps intuitive and easy to use
8. Code Organization: How to structure code with classes and methods
9. Documentation: How to write helpful comments and docstrings

💡 Tips for Students

1. Read the comments: Every section has detailed explanations
2. Experiment: Try changing colors, fonts, or messages
3. Debug: Use print() statements to see what's happening
4. Ask questions: If something is unclear, research it!
5. Build on it: Add new features like saving favorite cities

🔧 Common Issues & Solutions

"API Key Missing" Error

Problem: App shows error popup about missing API key

Solution:

1. Make sure you created the .env file (copy from .env.example)
2. Open .env and check that your API key is there
3. Make sure the line looks like: IQAIR_API_KEY=your-actual-key
4. No spaces around the = sign
5. No quotes around the API key

Example of correct .env file:

IQAIR_API_KEY=e6fa641d-6bc7-48db-94c8-f3f1e4a1a7ac

"ModuleNotFoundError: No module named 'dotenv'"

Solution: Install python-dotenv

pip install python-dotenv

"ModuleNotFoundError: No module named 'requests'"

Solution: Install all dependencies

pip install -r requirements.txt

"API Error: call_limit_reached"

Problem: You've used all 10,000 free API calls this month

Solutions:

• Wait until next month (limit resets)
• Create a new account with different email
• Upgrade to paid plan (if needed)

"API Error: incorrect_api_key"

Problem: Your API key is wrong or invalid

Solutions:

• Double-check you copied the entire API key
• Make sure there are no extra spaces
• Get a new API key from dashboard
• Make sure you verified your email

"API Error" or "Failed to fetch data"

Solutions:

• Check your internet connection
• Make sure city/state/country names are correct (use exact spelling)
• Try "Beijing, Beijing, China" as a test
• Check if API key is valid

"Could not determine your location"

Solution:

• Use manual entry instead of auto-detect
• Make sure you have internet connection
• Try entering city manually

.env File Not Working?

Checklist:

• File is named exactly .env (not .env.txt)
• File is in the same folder as main.py
• API key has no quotes: IQAIR_API_KEY=abc123 ✅
• API key has no spaces: IQAIR_API_KEY = abc123 ❌
• You saved the file after editing

License

Open source for educational purposes. Feel free to learn, modify, and share!