{
  "openapi": "3.1.0",
  "info": {
    "title": "Alergia España (Respira) — Public Environmental API",
    "version": "1.0.0",
    "description": "Real-time air quality, pollen and UV data for Spain. Anonymous, free, no auth. Aggregates 8 official Spanish aerobiology networks + CAMS/Copernicus + Open-Meteo into a 0–100 environmental health score.",
    "contact": {
      "name": "Alergia España",
      "email": "hola@chispa.dev",
      "url": "https://alergia.ai/soporte"
    },
    "license": {
      "name": "Free public service. Data redistribution: cite https://alergia.ai as source."
    }
  },
  "servers": [
    {
      "url": "https://api-respira.chispa.dev/api",
      "description": "Production API"
    }
  ],
  "paths": {
    "/v1/score": {
      "get": {
        "operationId": "getEnvironmentalScore",
        "summary": "Get current environmental score and conditions for a coordinate",
        "description": "Returns the 0–100 environmental health score plus underlying data (air quality pollutants, pollen counts, weather, UV) for the supplied latitude and longitude. Personalisation by allergies/conditions can be passed as URL-encoded JSON in the `prefs` parameter (optional — the endpoint works without).",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in decimal degrees, between -90 and 90. Use Spanish coordinates for best regional pollen coverage.",
            "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 40.4168 }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "Longitude in decimal degrees, between -180 and 180.",
            "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": -3.7038 }
          },
          {
            "name": "prefs",
            "in": "query",
            "required": false,
            "description": "Optional URL-encoded JSON with user preferences. Shape: {\"pollenSensitivities\": [\"grass\"], \"respiratoryConditions\": [\"asthma\"], \"ageGroup\": \"adult\", \"outdoorActivity\": \"moderate\", \"skinPhototype\": 3}",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScoreResponse" }
              }
            }
          },
          "400": { "description": "Invalid coordinates" },
          "429": { "description": "Rate limited" },
          "502": { "description": "Upstream data source unavailable" }
        }
      }
    },
    "/v1/forecast": {
      "get": {
        "operationId": "getEnvironmentalForecast",
        "summary": "Get next-24h hourly forecast for a coordinate",
        "description": "Returns the next 24 hourly entries with score, AQI, pollen breakdown, temperature and UV. Same prefs parameter as /v1/score.",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "example": 40.4168 } },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "example": -3.7038 } },
          { "name": "prefs", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ForecastResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScoreResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "score": {
                "type": "object",
                "properties": {
                  "overall": { "type": "integer", "minimum": 0, "maximum": 100, "description": "0–100 environmental health score." },
                  "aqi": { "type": "integer", "description": "Component score for air quality." },
                  "pollen": { "type": "integer" },
                  "uv": { "type": "integer" },
                  "comfort": { "type": "integer" },
                  "alerts": { "type": "array", "items": { "type": "string" } }
                }
              },
              "airQuality": {
                "type": "object",
                "properties": {
                  "aqi": { "type": "number", "description": "European AQI (0–100, higher = worse)." },
                  "pm25": { "type": "number" },
                  "pm10": { "type": "number" },
                  "no2": { "type": "number" },
                  "o3": { "type": "number" },
                  "so2": { "type": "number" },
                  "pollen": {
                    "type": "object",
                    "properties": {
                      "grass": { "type": "number", "nullable": true },
                      "olive": { "type": "number", "nullable": true },
                      "birch": { "type": "number", "nullable": true },
                      "alder": { "type": "number", "nullable": true },
                      "mugwort": { "type": "number", "nullable": true },
                      "ragweed": { "type": "number", "nullable": true }
                    }
                  }
                }
              },
              "weather": {
                "type": "object",
                "properties": {
                  "temperature": { "type": "number", "description": "Air temperature in °C." },
                  "humidity": { "type": "number" },
                  "windSpeed": { "type": "number" },
                  "uvIndex": { "type": "number" }
                }
              },
              "regionalPollen": {
                "type": "object",
                "nullable": true,
                "description": "Detailed pollen data when a regional Spanish aerobiology network covers the coordinate. Includes 20+ taxa with daily grain counts."
              },
              "pollenSource": {
                "type": "string",
                "enum": ["regional:palinocam", "regional:xac", "regional:avaic", "regional:zaragoza", "regional:ugr-andalucia", "regional:castilla-leon", "regional:andalucia", "regional:euskadi", "open-meteo"],
                "description": "Which data source provided the pollen reading. Regional networks are higher resolution; open-meteo is the CAMS/Copernicus fallback."
              }
            }
          }
        }
      },
      "ForecastResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "forecast": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "time": { "type": "string", "format": "date-time" },
                    "score": { "type": "integer" },
                    "europeanAqi": { "type": "number", "nullable": true },
                    "temperature": { "type": "number", "nullable": true },
                    "uvIndex": { "type": "number", "nullable": true }
                  }
                }
              },
              "alerts": { "type": "array", "items": { "type": "string" } }
            }
          }
        }
      }
    }
  }
}