WAQI Feed Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/waqi/main/json-schema/waqi-feed-response.json",
  "title": "WAQI Feed Response",
  "description": "JSON Schema for the World Air Quality Index (WAQI) feed API response. Used for /feed/{city}/, /feed/geo:{lat};{lng}/, and /feed/here/ endpoints.",
  "type": "object",
  "required": ["status", "data"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["ok", "error"],
      "description": "Response status. 'ok' indicates success; 'error' indicates a failure."
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/$defs/FeedData"
        },
        {
          "type": "string",
          "description": "Error message string returned when status is 'error'"
        }
      ]
    }
  },
  "$defs": {
    "FeedData": {
      "type": "object",
      "title": "FeedData",
      "description": "Air quality data payload for a monitoring station",
      "required": ["aqi", "idx", "city", "iaqi", "time"],
      "properties": {
        "aqi": {
          "type": "integer",
          "minimum": 0,
          "description": "Overall Air Quality Index. Scale: 0-50 Good, 51-100 Moderate, 101-150 Unhealthy for Sensitive Groups, 151-200 Unhealthy, 201-300 Very Unhealthy, 301+ Hazardous."
        },
        "idx": {
          "type": "integer",
          "description": "Unique numeric identifier for the monitoring station in the WAQI network"
        },
        "attributions": {
          "type": "array",
          "description": "List of agencies and organizations contributing the data",
          "items": {
            "$ref": "#/$defs/Attribution"
          }
        },
        "city": {
          "$ref": "#/$defs/CityInfo"
        },
        "dominentpol": {
          "type": "string",
          "description": "The pollutant with the highest individual AQI sub-index, driving the overall AQI",
          "enum": ["pm25", "pm10", "no2", "co", "so2", "o3"]
        },
        "iaqi": {
          "$ref": "#/$defs/IndividualAQI"
        },
        "time": {
          "$ref": "#/$defs/TimeInfo"
        },
        "forecast": {
          "$ref": "#/$defs/Forecast"
        },
        "debug": {
          "type": "object",
          "description": "Internal debug metadata",
          "properties": {
            "sync": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp of the last backend synchronization"
            }
          }
        }
      }
    },
    "Attribution": {
      "type": "object",
      "title": "Attribution",
      "description": "Data source attribution",
      "required": ["url", "name"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL of the monitoring agency or data provider"
        },
        "name": {
          "type": "string",
          "description": "Display name of the monitoring agency or data provider"
        },
        "logo": {
          "type": "string",
          "description": "Filename of the attribution logo image"
        }
      }
    },
    "CityInfo": {
      "type": "object",
      "title": "CityInfo",
      "description": "Location information for the monitoring station",
      "required": ["geo", "name", "url"],
      "properties": {
        "geo": {
          "type": "array",
          "description": "Geographic coordinates as [latitude, longitude]",
          "items": {
            "type": "number",
            "format": "float"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "name": {
          "type": "string",
          "description": "Human-readable name of the city or station location"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL for this station on aqicn.org"
        }
      }
    },
    "IndividualAQI": {
      "type": "object",
      "title": "IndividualAQI",
      "description": "Per-pollutant AQI sub-index values and additional meteorological measurements. All properties are optional as availability depends on the station's sensor suite.",
      "properties": {
        "co": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Carbon Monoxide (CO) sub-index"
        },
        "no2": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Nitrogen Dioxide (NO2) sub-index"
        },
        "o3": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Ozone (O3) sub-index"
        },
        "pm10": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Particulate Matter ≤10 micrometers (PM10) sub-index"
        },
        "pm25": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Particulate Matter ≤2.5 micrometers (PM2.5) sub-index"
        },
        "so2": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Sulfur Dioxide (SO2) sub-index"
        },
        "t": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Temperature (degrees Celsius)"
        },
        "h": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Relative humidity (%)"
        },
        "p": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Atmospheric pressure (hPa)"
        },
        "w": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Wind speed (m/s)"
        },
        "wg": {
          "$ref": "#/$defs/PollutantValue",
          "description": "Wind gust speed (m/s)"
        }
      },
      "additionalProperties": {
        "$ref": "#/$defs/PollutantValue"
      }
    },
    "PollutantValue": {
      "type": "object",
      "title": "PollutantValue",
      "description": "A single measured or derived value",
      "required": ["v"],
      "properties": {
        "v": {
          "type": "number",
          "description": "The numeric value of the measurement or sub-index"
        }
      }
    },
    "TimeInfo": {
      "type": "object",
      "title": "TimeInfo",
      "description": "Timestamp information for the data observation",
      "required": ["s", "tz", "v"],
      "properties": {
        "s": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$",
          "description": "Station local time in 'YYYY-MM-DD HH:MM:SS' format"
        },
        "tz": {
          "type": "string",
          "pattern": "^[+-]\\d{2}:\\d{2}$",
          "description": "UTC timezone offset of the station (e.g., '+08:00', '-05:00')"
        },
        "v": {
          "type": "integer",
          "description": "Unix epoch timestamp (seconds since 1970-01-01T00:00:00Z)"
        },
        "iso": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 formatted timestamp with timezone offset"
        }
      }
    },
    "Forecast": {
      "type": "object",
      "title": "Forecast",
      "description": "Multi-day air quality forecast data (typically 3-8 days ahead)",
      "properties": {
        "daily": {
          "type": "object",
          "description": "Daily forecast broken down by pollutant",
          "properties": {
            "o3": {
              "type": "array",
              "items": { "$ref": "#/$defs/ForecastDay" },
              "description": "Daily Ozone (O3) AQI forecast"
            },
            "pm10": {
              "type": "array",
              "items": { "$ref": "#/$defs/ForecastDay" },
              "description": "Daily PM10 AQI forecast"
            },
            "pm25": {
              "type": "array",
              "items": { "$ref": "#/$defs/ForecastDay" },
              "description": "Daily PM2.5 AQI forecast"
            },
            "uvi": {
              "type": "array",
              "items": { "$ref": "#/$defs/ForecastDay" },
              "description": "Daily UV Index forecast"
            }
          }
        }
      }
    },
    "ForecastDay": {
      "type": "object",
      "title": "ForecastDay",
      "description": "AQI statistics for a single forecast day",
      "required": ["avg", "day", "max", "min"],
      "properties": {
        "avg": {
          "type": "number",
          "description": "Average AQI value for the forecast day"
        },
        "day": {
          "type": "string",
          "format": "date",
          "description": "Forecast date in YYYY-MM-DD format"
        },
        "max": {
          "type": "number",
          "description": "Maximum predicted AQI value for the forecast day"
        },
        "min": {
          "type": "number",
          "description": "Minimum predicted AQI value for the forecast day"
        }
      }
    }
  }
}