{
  "openapi": "3.0.3",
  "info": {
    "title": "weatherAI.io Decision API",
    "version": "1.0.0",
    "description": "One call turns the weather into a decision: a verdict, a 0-100 score, the best time windows and the risks for an activity at a place and date. 1,000 free calls every month, then £0.0012 per successful call from prepaid credit (VAT included). Failed calls are not charged. AI agents can also use the MCP server at https://api.weatherai.io/mcp."
  },
  "servers": [
    {
      "url": "https://api.weatherai.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Window": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "example": "2026-10-18 07:00"
          },
          "end": {
            "type": "string",
            "example": "2026-10-18 10:00"
          },
          "score": {
            "type": "integer",
            "example": 91
          }
        }
      },
      "Risk": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "example": "rain"
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "moderate",
              "high",
              "severe",
              "extreme"
            ]
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "detail": {
            "type": "string",
            "example": "70% chance of rain"
          }
        }
      },
      "Decision": {
        "type": "object",
        "properties": {
          "location": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "region": { "type": "string" },
              "country": { "type": "string" },
              "lat": { "type": "number" },
              "lon": { "type": "number" },
              "tz_id": { "type": "string" },
              "localtime": { "type": "string" }
            }
          },
          "activity": {
            "type": "string",
            "enum": [
              "running",
              "cycling",
              "outdoor-event",
              "beach",
              "laundry-drying",
              "stargazing",
              "hiking",
              "golf",
              "tennis",
              "dog-walking",
              "gardening",
              "fishing",
              "sailing",
              "drone-flying",
              "exterior-painting",
              "concrete-pour",
              "roofing",
              "crop-spraying",
              "outdoor-work",
              "driving",
              "solar-pv"
            ]
          },
          "date": { "type": "string", "format": "date" },
          "verdict": { "type": "string", "enum": ["great","good","fair","poor","avoid"] },
          "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Quality of the best opportunity on that date (best window)." },
          "best_windows": { "type": "array", "items": { "$ref": "#/components/schemas/Window" } },
          "risks": { "type": "array", "items": { "$ref": "#/components/schemas/Risk" } },
          "summary": { "type": "string", "example": "Great conditions for a run in London; best 07:00–10:00. Watch for rain from 14:00." },
          "data": { "type": "object", "additionalProperties": true, "description": "Key figures for the hours considered (temperatures, rain, wind, UV, sunrise/sunset; moon for stargazing). When available: air quality (air_quality, air_quality_us_epa_max, pm2_5_max, pm10_max), pollen levels (pollen_tree, pollen_grass, pollen_weed, pollen_max: none/low/moderate/high/very high), sunshine_pct_avg, sunshine_hours, solar_ghi_max_wm2, solar_dni_max_wm2, solar_gti_max_wm2, solar_energy_kwh_m2, solar_panel_energy_kwh_m2, wetbulb_max, snow_total_cm (snow_total_in), pressure_mb (pressure_in), pressure_trend and wind_dir." },
          "hourly": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "score": { "type": "integer" }, "main_issue": { "type": "string", "nullable": true } } }, "description": "Only with detail=hourly." },
          "billing": { "type": "object", "properties": { "charged": { "type": "string", "enum": ["free","credit"] }, "cost_gbp": { "type": "string", "example": "0.0012" }, "free_remaining": { "type": "integer" }, "balance_gbp": { "type": "string" } } }
        }
      },
      "DayRanking": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "weekday": { "type": "string" },
          "verdict": { "type": "string", "enum": ["great","good","fair","poor","avoid"] },
          "score": { "type": "integer" },
          "best_window": { "$ref": "#/components/schemas/Window" },
          "top_risks": { "type": "array", "items": { "$ref": "#/components/schemas/Risk" } },
          "summary": { "type": "string" }
        }
      },
      "BestDay": {
        "type": "object",
        "properties": {
          "location": { "type": "object" },
          "activity": { "type": "string" },
          "days_checked": { "type": "integer" },
          "summary": { "type": "string" },
          "best": { "$ref": "#/components/schemas/DayRanking" },
          "days": { "type": "array", "items": { "$ref": "#/components/schemas/DayRanking" } },
          "billing": { "type": "object" }
        }
      },
      "RuleLimits": {
        "type": "object",
        "properties": {
          "max_calls_per_month": { "type": "integer" },
          "max_calls_per_day": { "type": "integer" },
          "max_calls_per_minute": { "type": "integer" }
        }
      },
      "Widget": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }
        }
      }
    }
  },
  "paths": {}
}