{
  "openapi": "3.1.0",
  "info": {
    "title": "WeatherXM FACT Historical Benchmark",
    "version": "2.1.0",
    "description": "Read-only 2025 publication data scoring all 45 NWP & AI forecast models (WeatherXM MOSAIC [MOSAIC], meteoblue [METEOBLUE], meteoblue station-mLM [mLM], ECMWF IFS [IFS025, IFSHRES], ECMWF AIFS AI [AIFS025], NOAA GFS [GFS05, GFS025], NOAA HRRR [HRRR], NOAA National Blend of Models [NBM], NOAA NAM [NAM3, NAM5, NAM12, NAMAK], DWD ICON [ICON, ICONEU, ICOND2], UK Met Office [UMGLOBAL10, UKMO2], ECCC GEM [GEM15, GEM2], Meteo-France ARPEGE/AROME [MFGLOBAL, MFEU, MFFR], COSMO [COSMOI2, COSMOM5], HARMONIE-AROME [HARMONIE], JMA MSM [MSM], WRF [WRFGR, WRFAMS], meteoblue NEMS/NMM [NEMSGLOBAL, NEMSGLOBAL_E, NEMS4, NEMS12, NEMS12_E, NEMSAF01, NEMSAS02, NEMSCAM, NEMSIN, NEMSNZ, NEMSSA, NMM4, NMM22], and regional AF01, AS01, SA01) against 8,927 physical WeatherXM ground stations. No live station coverage claims, forecasts, guaranteed improvements or billing."
  },
  "servers": [
    {
      "url": "https://fact.weatherxm.com",
      "description": "WeatherXM FACT Production Server"
    }
  ],
  "paths": {
    "/api/v1/fact/best-model": {
      "get": {
        "operationId": "getBestForecastModel",
        "summary": "Read the published historical cell or station champion across all 45 weather forecast models. Provide (lat, lon) or station_or_report_id.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": -90, "maximum": 90 }
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": -180, "maximum": 180 }
          },
          {
            "name": "station_or_report_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 80 },
            "description": "Optional WeatherXM station UUID or custom site evaluation report ID (e.g. STUDY-...)"
          },
          {
            "name": "variable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["temperature", "wind_speed", "precipitation", "humidity"],
              "default": "temperature"
            }
          },
          {
            "name": "lead_day",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["all", "0", "1", "2", "3", "4", "5", "6", "7"]
            }
          },
          {
            "name": "exclude_commissioned",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical results and provenance with explicit unknowns",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": {
            "description": "Invalid or unsupported query",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "503": {
            "description": "Index unavailable",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    },
    "/api/v1/fact/blind-spot": {
      "get": {
        "operationId": "checkGroundTruthCoverage",
        "summary": "Check historical publication coverage for a coordinate or station_or_report_id, plus interactive map deep-link and WeatherXM station overview link (weatherxm.com/stations).",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": -90, "maximum": 90 }
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": -180, "maximum": 180 }
          },
          {
            "name": "station_or_report_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 80 }
          },
          {
            "name": "variable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["temperature", "wind_speed", "precipitation", "humidity"],
              "default": "temperature"
            }
          },
          {
            "name": "lead_day",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["all", "0", "1", "2", "3", "4", "5", "6", "7"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical results and provenance with explicit unknowns",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": {
            "description": "Invalid or unsupported query",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "503": {
            "description": "Index unavailable",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    },
    "/api/v1/fact/leaderboard": {
      "get": {
        "operationId": "getFactLeaderboard",
        "summary": "Global curves across all 45 models at a specific lead (default 1), or country cell-win summaries at all (default for country).",
        "parameters": [
          {
            "name": "variable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["temperature", "wind_speed", "precipitation", "humidity"],
              "default": "temperature"
            }
          },
          {
            "name": "lead_day",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["all", "0", "1", "2", "3", "4", "5", "6", "7"]
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 80 }
          },
          {
            "name": "exclude_commissioned",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical results and provenance with explicit unknowns",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": {
            "description": "Invalid or unsupported query",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "503": {
            "description": "Index unavailable",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    },
    "/api/v1/fact/compare": {
      "get": {
        "operationId": "getModelHeadToHead",
        "summary": "Global source-specific error curves across any of the 45 FACT models with commissioned-model and cohort caveats.",
        "parameters": [
          {
            "name": "variable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["temperature", "wind_speed", "precipitation", "humidity"],
              "default": "temperature"
            }
          },
          {
            "name": "models",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "description": "Comma-separated canonical IDs, at most ten." }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical results and provenance with explicit unknowns",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": {
            "description": "Invalid or unsupported query",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "503": {
            "description": "Index unavailable",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          }
        }
      }
    }
  }
}