API Overview

Reference architecture for AQI prediction APIs

API Reference: This section describes a reference API design for AQI prediction systems. For actual implementation status, check the GitHub repository.

Introduction

This API reference describes a typical REST API design for machine learning-powered air quality predictions. The patterns shown here demonstrate best practices for structuring prediction endpoints, authentication, and data formats.

Base URL

All API requests should be made to:

https://api.aqipredictor.com/api/v1

For development and testing:

https://sandbox-api.aqipredictor.com/api/v1

API Versioning

The API version is included in the URL path. The current version is v1. When breaking changes are introduced, a new version will be released and the previous version will be maintained for a transition period.

Request Format

All POST requests must include:

• Content-Type: application/json header
• Valid JSON request body
• Authentication header (see Authentication)

Response Format

All API responses return JSON with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  },
  "timestamp": "2026-03-05T14:30:00Z"
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Temperature value must be between -50 and 60 degrees Celsius",
    "details": {
      "parameter": "temperature",
      "value": 75
    }
  },
  "timestamp": "2026-03-05T14:30:00Z"
}

HTTP Status Codes

The API uses standard HTTP status codes:

Status Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid parameters or request format
401	Unauthorized - Missing or invalid API key
403	Forbidden - Valid credentials but insufficient permissions
404	Not Found - Endpoint or resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server encountered an error
503	Service Unavailable - Temporary service interruption

Error Codes

Error Code	Description
INVALID_API_KEY	The provided API key is invalid or expired
MISSING_PARAMETER	Required parameter is missing from request
INVALID_PARAMETER	Parameter value is invalid or out of range
RATE_LIMIT_EXCEEDED	Too many requests, please slow down
MODEL_UNAVAILABLE	ML model is temporarily unavailable
PREDICTION_FAILED	Prediction could not be completed
BATCH_TOO_LARGE	Batch size exceeds maximum allowed

Rate Limits

Rate limits vary by subscription tier. Upgrade your plan for higher limits.

Tier	Requests per minute	Requests per day
Free	10	1,000
Basic	60	10,000
Pro	300	100,000
Enterprise	Custom	Custom

When you exceed the rate limit, you’ll receive a 429 status code with headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709650800

Data Ranges

Input parameters must fall within these validated ranges:

Environmental Parameters

• Temperature: -50°C to 60°C
• Humidity: 0% to 100%
• Pressure: 900 hPa to 1100 hPa
• Wind Speed: 0 km/h to 200 km/h
• PM2.5: 0 µg/m³ to 500 µg/m³
• PM10: 0 µg/m³ to 600 µg/m³
• NO2: 0 ppb to 500 ppb
• O3: 0 ppb to 400 ppb
• CO: 0 ppm to 50 ppm

AQI Scale Reference

The API returns AQI values following the US EPA standard:

AQI Range	Level	Health Implications
0-50	Good	Air quality is satisfactory
51-100	Moderate	Acceptable for most people
101-150	Unhealthy for Sensitive Groups	Sensitive groups may experience health effects
151-200	Unhealthy	Everyone may begin to experience health effects
201-300	Very Unhealthy	Health alert: everyone may experience serious effects
301-500	Hazardous	Health warning of emergency conditions

SDK and Client Libraries

Official SDK libraries are coming soon. Use the REST API directly for now.

Planned client libraries:

• Python SDK
• JavaScript/TypeScript SDK
• Java SDK
• Go SDK

Support

For API support:

• Documentation: https://docs.aqipredictor.com
• Email: [e-mail]
• Status page: https://status.aqipredictor.com