Forecast API

The Predict API provides site-level PM2.5 air quality forecasts generated by AirQo forecasting models. The service supports both daily forecasts (7-day horizon) and hourly forecasts (up to 240 hours ahead by default). Forecasts can be retrieved for individual monitoring sites, grids, or cohorts of monitoring sites.

Tier requirement

Forecasts require a Premium Tier subscription.

---

Daily Forecasting Endpoint

GET /api/v2/predict/daily-forecasting/

Returns PM2.5 forecasts for the next 7 days, grouped by monitoring site.

Supported Parameters

Parameter	Description
site_id	Forecast for a single site
grid_id	Forecasts for all sites within a grid
cohort_id	Forecasts for all sites within a cohort
scope	Optional — "grid" or "cohort" to disambiguate when a scope ID could match either type

Only one of site_id, grid_id, or cohort_id may be provided per request.

Response Structure

{
  "success": true,
  "data": {
    "start_date": "2026-06-03",
    "end_date": "2026-06-09",
    "days": 7,
    "total": 1,
    "units": {
      "pm2_5": "ug/m3",
      "air_temperature": "degC",
      "relative_humidity": "%",
      "air_pressure_at_sea_level": "hPa",
      "precipitation_amount": "mm",
      "cloud_area_fraction": "%",
      "wind_speed": "m/s",
      "wind_from_direction": "compass",
      "forecast_confidence": "%"
    },
    "forecasts": [
      {
        "site_details": {
          "site_id": "64f7b3e8c9d25a0013f2d456",
          "site_name": "Kampala Central",
          "site_latitude": 0.3476,
          "site_longitude": 32.5825
        },
        "forecasts": [
          {
            "date": "2026-06-03",
            "forecast": {
              "pm2_5_mean": 28.4,
              "pm2_5_low": 22.1,
              "pm2_5_high": 34.8,
              "pm2_5_min": 19.0,
              "pm2_5_max": 37.2,
              "forecast_confidence": 84.5
            },
            "aqi": {
              "category": "Moderate",
              "label": "Air quality is acceptable for most people.",
              "trend_message": "Air pollution may increase over the next 24 hours."
            },
            "met": {
              "air_temperature": 24.7,
              "relative_humidity": 72.1,
              "air_pressure_at_sea_level": 1012.3,
              "precipitation_amount": 0.0,
              "cloud_area_fraction": 45.0,
              "wind_speed": 3.2,
              "wind_from_direction": "NE"
            }
          }
        ]
      }
    ]
  }
}

---

Hourly Forecasting Endpoint

GET /api/v2/predict/hourly-forecasting/

Returns hourly PM2.5 forecasts beginning from the current forecast hour.

Supported Parameters

Parameter	Type	Description
site_id	string	Forecast for a single site
grid_id	string	Forecasts for all sites within a grid
cohort_id	string	Forecasts for all sites within a cohort
scope	string	Optional — "grid" or "cohort" to disambiguate
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 10, max: 100)

Only one of site_id, grid_id, or cohort_id may be provided per request.

Key Features

• Default forecast horizon: 240 hours (10 days)
• Pagination support across all sites in a grid or cohort
• AQI category, advisory label, and trend message included
• Uncertainty range via pm2_5_q10 and pm2_5_q90 percentiles
• Meteorological context included per hour

Response Structure

{
  "success": true,
  "data": {
    "start_timestamp": "2026-06-07T10:00:00+00:00",
    "end_timestamp": "2026-06-17T10:00:00+00:00",
    "hours": 240,
    "total": 10,
    "page": 1,
    "pages": 24,
    "units": {
      "pm2_5": "ug/m3",
      "air_temperature": "degC",
      "relative_humidity": "%",
      "air_pressure_at_sea_level": "hPa",
      "precipitation_amount": "mm",
      "cloud_area_fraction": "%",
      "wind_speed": "m/s",
      "wind_from_direction": "compass",
      "forecast_confidence": "%"
    },
    "forecasts": [
      {
        "site_details": {
          "site_id": "64f7b3e8c9d25a0013f2d456",
          "site_name": "Kampala Central",
          "site_latitude": 0.3476,
          "site_longitude": 32.5825
        },
        "forecasts": [
          {
            "timestamp": "2026-06-07T10:00:00+00:00",
            "forecast": {
              "pm2_5_mean": 28.4,
              "pm2_5_q10": 20.1,
              "pm2_5_q90": 36.2,
              "forecast_confidence": 84.5
            },
            "aqi": {
              "category": "Moderate",
              "label": "Air quality is acceptable for most people.",
              "trend_message": "Air pollution may increase over the next hour."
            },
            "met": {
              "air_temperature": 24.7,
              "relative_humidity": 72.1,
              "air_pressure_at_sea_level": 1012.3,
              "precipitation_amount": 0.0,
              "cloud_area_fraction": 45.0,
              "wind_speed": 3.2,
              "wind_from_direction": "NE"
            }
          }
        ]
      }
    ]
  }
}

---

Scope (Grid and Cohort) Forecasting

When grid-based or cohort-based forecasting is requested, the API supports aggregated forecast retrieval through:

GET /api/v2/predict/hourly-forecasting/<scope_id>
GET /api/v2/predict/daily-forecasting/<scope_id>

The <scope_id> path parameter accepts a grid ID or cohort ID. Use the optional scope query parameter ("grid" or "cohort") if the ID is ambiguous.

Scope Metadata Returned

The fields below are returned inside the top-level data object ({ "success": true, "data": { ... } }).

{
  "scope": {
    "type": "grid",
    "id": "64b7ac8fd7249f0029feca80",
    "grid_id": "64b7ac8fd7249f0029feca80"
  },
  "sites_count": 3,
  "sites_with_forecasts_count": 2,
  "site_names": [
    "Kampala Central",
    "Makerere"
  ],
  "forecasts": [
    {
      "site_details": {
        "site_id": "68fca1da53b8b4001372887f",
        "site_name": "Buyala 1 Mpigi",
        "site_latitude": 0.313465,
        "site_longitude": 32.405833
      },
      "start_date": "2026-06-03",
      "end_date": "2026-06-09",
      "days": 7,
      "total": 7,
      "forecasts": [
        {
          "date": "2026-06-03",
          "forecast": {
            "pm2_5_mean": 24.1,
            "pm2_5_low": 18.0,
            "pm2_5_high": 29.5
          }
        }
      ]
    }
  ]
}

---

Response Field Reference

Daily forecast item

Field	Type	Description
date	string	Forecast date (ISO 8601 date)
forecast.pm2_5_mean	number	Mean PM2.5 forecast in µg/m³
forecast.pm2_5_low	number	Lower bound of forecast range
forecast.pm2_5_high	number	Upper bound of forecast range
forecast.pm2_5_min	number	Minimum predicted value across the day
forecast.pm2_5_max	number	Maximum predicted value across the day
forecast.forecast_confidence	number	Model confidence (0–100%)
aqi.category	string	AQI category name (see AQI Categories below)
aqi.label	string	Health advisory for this AQI level
aqi.trend_message	string	Expected direction of PM2.5 over the next period
met.air_temperature	number	Air temperature in °C
met.relative_humidity	number	Relative humidity in %
met.air_pressure_at_sea_level	number	Atmospheric pressure in hPa
met.precipitation_amount	number	Expected rainfall in mm
met.cloud_area_fraction	number	Cloud cover in %
met.wind_speed	number	Wind speed in m/s
met.wind_from_direction	string	Wind direction as compass point (e.g. "NE", "SW")

Hourly forecast item

Same as daily, with the following differences:

Field	Type	Description
timestamp	string	Forecast hour (ISO 8601 datetime with timezone)
forecast.pm2_5_q10	number	10th percentile — lower uncertainty bound
forecast.pm2_5_q90	number	90th percentile — upper uncertainty bound

pm2_5_low / pm2_5_high are not included in hourly items; use pm2_5_q10 / pm2_5_q90 instead.

---

AQI Categories

Forecasts include an AQI category derived from the predicted PM2.5 mean value.

Category	PM2.5 range (µg/m³)	Color
Good	0.0 – 9.0	Green (#00e400)
Moderate	9.1 – 35.4	Yellow (#ffff00)
Unhealthy for Sensitive Groups	35.5 – 55.4	Orange (#ff7e00)
Unhealthy	55.5 – 125.4	Red (#ff0000)
Very Unhealthy	125.5 – 225.4	Purple (#8f3f97)
Hazardous	225.5+	Maroon (#7e0023)

---

Validation Error

Returned when more than one of site_id, grid_id, or cohort_id is provided in the same request.

{
  "success": false,
  "message": "Please specify only one of site_id, grid_id, or cohort_id.",
  "data": {
    "forecasts": []
  }
}

---

Caching and Update Frequency

Forecast results are cached per request parameters. Cache is invalidated automatically when the underlying forecast data changes — typically aligned with model run cycles. For most integrations, caching responses for 1–3 hours gives a good balance between API call volume and data freshness. See Best Practices → for caching guidance.