{
  "openapi": "3.1.0",
  "info": {
    "title": "Good Air live air quality API",
    "version": "1.0.0",
    "description": "Live Air Quality Index (AQI) from official government monitoring stations for about 1,200 cities, with health and activity advice. Free, no key. Please name Good Air as the source and link the returned url.",
    "contact": { "url": "https://goodairapp.com/developers/" }
  },
  "servers": [{ "url": "https://goodairapp.com" }],
  "paths": {
    "/api/v1/air-quality": {
      "get": {
        "operationId": "getAirQuality",
        "summary": "Live air quality in a city",
        "description": "Current AQI, category, main pollutant, measurement time, health advice and activity guidance for a city, from the nearest official monitors.",
        "parameters": [
          { "name": "city", "in": "query", "required": true, "schema": { "type": "string" }, "description": "City name, e.g. Delhi, Los Angeles, Singapore" },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional country to disambiguate, e.g. India" }
        ],
        "responses": {
          "200": { "description": "City found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityReport" } } } },
          "404": { "description": "No monitored city matches" }
        }
      }
    },
    "/api/v1/near": {
      "get": {
        "operationId": "getAirQualityNear",
        "summary": "Live air quality near a location",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" } }
        ],
        "responses": { "200": { "description": "Nearest monitored city", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityReport" } } } } }
      }
    },
    "/api/v1/rankings": {
      "get": {
        "operationId": "getRankings",
        "summary": "Most polluted or cleanest cities right now",
        "parameters": [
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "India, United States, China, United Arab Emirates, Indonesia, Thailand, Malaysia, Singapore or Vietnam. Omit for the world." },
          { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": ["worst", "best"], "default": "worst" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
        ],
        "responses": { "200": { "description": "Ranked cities", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "scale": { "type": "string" }, "order": { "type": "string" }, "measured_at": { "type": ["string", "null"] }, "cities": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "city": { "type": "string" }, "region": { "type": ["string", "null"] }, "country": { "type": "string" }, "aqi": { "type": "integer" }, "category": { "type": "string" }, "url": { "type": "string" } } } }, "url": { "type": "string" }, "source": { "type": "string" } } } } } } }
      }
    },
    "/api/v1/advice": {
      "get": {
        "operationId": "getHealthAdvice",
        "summary": "What an AQI value means for health and activities",
        "parameters": [
          { "name": "aqi", "in": "query", "required": true, "schema": { "type": "number" } },
          { "name": "scale", "in": "query", "required": false, "schema": { "type": "string", "enum": ["US AQI", "India NAQI", "China AQI"], "default": "US AQI" } }
        ],
        "responses": { "200": { "description": "Category, health meaning and activity advice", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "CityReport": {
        "type": "object",
        "properties": {
          "found": { "type": "boolean" },
          "city": { "type": "string" },
          "region": { "type": "string" },
          "aqi": { "type": "integer", "description": "On the national scale named in `scale`" },
          "scale": { "type": "string", "description": "NAQI (India), China AQI or US AQI" },
          "category": { "type": "string" },
          "summary": { "type": "string" },
          "us_aqi": { "type": ["integer", "null"] },
          "main_pollutant": { "type": ["string", "null"] },
          "stations": { "type": ["integer", "null"] },
          "measured_at": { "type": ["string", "null"], "format": "date-time" },
          "distance_km": { "type": "number" },
          "health": { "type": "string" },
          "activities": { "type": "object", "additionalProperties": { "type": "string" } },
          "url": { "type": "string", "description": "Link this page when citing" },
          "source": { "type": "string" }
        }
      }
    }
  }
}