Documentation Note: This quickstart demonstrates the intended usage patterns for AQI prediction. For actual implementation and availability, please refer to the GitHub repository .Get Started in 3 Steps This guide demonstrates the typical workflow for installing and using an AQI prediction system.
Install AQI Predictor
Install the Python package using pip: pip install aqi-predictor
AQI Predictor requires Python 3.8 or higher. Check your Python version with python --version
Get Your API Key
Sign up for a free account and obtain your API key. Contact your administrator or visit the project repository to get access credentials. Once you have your API key: Keep your API key secure! Never commit it to version control or share it publicly.
Store your API key as an environment variable: export AQI_API_KEY = "your_api_key_here"
Or create a .env file: AQI_API_KEY = your_api_key_here
Make Your First Prediction
Create a Python script and make your first AQI prediction: from aqi_predictor import AQIClient import os # Initialize the client client = AQIClient( api_key = os.getenv( "AQI_API_KEY" )) # Prepare environmental data environmental_data = { "temperature" : 25.5 , # Temperature in Celsius "humidity" : 65 , # Relative humidity (%) "pressure" : 1013.25 , # Atmospheric pressure (hPa) "wind_speed" : 3.2 , # Wind speed (m/s) "pm25" : 12.3 , # PM2.5 concentration (μg/m³) "pm10" : 22.1 , # PM10 concentration (μg/m³) "no2" : 15.2 , # NO2 concentration (ppb) "o3" : 35.6 , # O3 concentration (ppb) "location" : { "lat" : 37.7749 , # San Francisco coordinates "lon" : - 122.4194 } } # Get prediction prediction = client.predict(environmental_data) # Display results print ( f "Predicted AQI: { prediction.aqi } " ) print ( f "Category: { prediction.category } " ) print ( f "Confidence: { prediction.confidence :.2%} " ) print ( f "Health Recommendation: { prediction.health_message } " )
Run your script:
Predicted AQI: 42 Category: Good Confidence: 94.23% Health Recommendation: Air quality is satisfactory, and air pollution poses little or no risk.
Understanding the Response The prediction response includes several fields:
The predicted Air Quality Index value (0-500)
The AQI category: Good, Moderate, Unhealthy for Sensitive Groups, Unhealthy, Very Unhealthy, or Hazardous
Model confidence score (0-1) indicating prediction reliability
Human-readable health recommendation based on the predicted AQI
ISO 8601 timestamp of when the prediction was made
Breakdown of individual pollutant contributions to the AQI
Try Different Scenarios Experiment with different environmental conditions to see how they affect AQI predictions:
High Pollution
Clean Air
Seasonal Variations
# Simulate high pollution conditions high_pollution = { "temperature" : 32.0 , "humidity" : 45 , "wind_speed" : 1.2 , # Low wind speed "pm25" : 85.4 , # High PM2.5 "pm10" : 120.3 , # High PM10 "no2" : 62.1 , "location" : { "lat" : 34.0522 , "lon" : - 118.2437 } } result = client.predict(high_pollution) # Expected: AQI ~150-180 (Unhealthy)
# Simulate clean air conditions clean_air = { "temperature" : 18.0 , "humidity" : 55 , "wind_speed" : 5.8 , # Good wind speed "pm25" : 4.2 , # Low PM2.5 "pm10" : 8.5 , # Low PM10 "no2" : 8.3 , "location" : { "lat" : 47.6062 , "lon" : - 122.3321 } } result = client.predict(clean_air) # Expected: AQI ~20-30 (Good)
# Winter conditions (potential for inversions) winter = { "temperature" : 5.0 , "humidity" : 75 , "wind_speed" : 2.1 , "pm25" : 28.6 , "pm10" : 45.2 , "no2" : 32.4 , } # Summer conditions (potential for ozone) summer = { "temperature" : 35.0 , "humidity" : 40 , "wind_speed" : 3.5 , "pm25" : 18.2 , "pm10" : 28.1 , "o3" : 82.5 , # High ozone }
Batch Predictions Need to process multiple locations or time periods? Use batch predictions:
from aqi_predictor import AQIClient client = AQIClient( api_key = os.getenv( "AQI_API_KEY" )) # Multiple predictions in one request locations = [ { "temperature" : 25.5 , "humidity" : 65 , "pm25" : 12.3 , "location" : { "lat" : 37.7749 , "lon" : - 122.4194 }}, { "temperature" : 28.1 , "humidity" : 58 , "pm25" : 18.7 , "location" : { "lat" : 34.0522 , "lon" : - 118.2437 }}, { "temperature" : 22.3 , "humidity" : 72 , "pm25" : 9.1 , "location" : { "lat" : 40.7128 , "lon" : - 74.0060 }}, ] predictions = client.batch_predict(locations) for i, pred in enumerate (predictions): print ( f "Location { i + 1 } : AQI { pred.aqi } - { pred.category } " )
Using the REST API Prefer to use the REST API directly? Here’s how:
curl -X POST https://api.aqipredictor.com/v1/predict \ -H "X-API-Key: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "temperature": 25.5, "humidity": 65, "pm25": 12.3, "pm10": 22.1, "no2": 15.2, "location": {"lat": 37.7749, "lon": -122.4194} }'
Next Steps Now that you’ve made your first prediction, explore more advanced features:
Installation Guide Learn about advanced installation options and dependencies
Core Concepts Understand how AQI prediction works under the hood
Training Models Train custom models on your regional data
API Reference Explore the complete API documentation
Pro tip: Start with pre-trained models for quick results, then train custom models on your regional data for improved accuracy.