{
  "openapi": "3.0.2",
  "info": {
    "title": "Weather API (v2)",
    "description": "The v2 endpoint interface for the Weather Provider API",
    "contact": {
      "name": "Verbindingsteam",
      "email": "weather.provider@alliander.com"
    },
    "version": "2.9.0"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8080/api/v2"
    }
  ],
  "paths": {
    "/weather/sources": {
      "get": {
        "tags": [
          "sync"
        ],
        "summary": "Get Sources",
        "description": "List all of the Weather Sources available.\n\nAn API route that returns a list of all the Weather Sources available from the WeatherController.\nEach Source contains information about the source and a list of the Models available for that Source.\n\nArgs:\n    None\nReturns:\n    A list of all Source available from the WeatherController",
        "operationId": "get_sources_weather_sources_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/WeatherSource"
                  },
                  "type": "array",
                  "title": "Response Get Sources Weather Sources Get"
                }
              }
            }
          }
        }
      }
    },
    "/weather/sources/{source_id}": {
      "get": {
        "tags": [
          "sync"
        ],
        "summary": "Get Source",
        "description": "List all the Models available  for the Source.\n\nAn API route that returns a list of all the Models available for the given Source ID.\n\nArgs:\n    source_id: The source ID for the given source\nReturns:\n    A list of all Models available for the given source",
        "operationId": "get_source_weather_sources__source_id__get",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Source Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WeatherSource"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/weather/sources/{source_id}/models": {
      "get": {
        "tags": [
          "sync"
        ],
        "summary": "Get Sync Models",
        "description": "List all the synchronous Models available for the selected Source.\n\nAn API function that returns all of the synchronous models available for the given source.\n\nArgs:\n    source_id: The source ID for the given source\nReturns:\n    A list of all synchronous Models available for the given source",
        "operationId": "get_sync_models_weather_sources__source_id__models_get",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Source Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherModel"
                  },
                  "title": "Response Get Sync Models Weather Sources  Source Id  Models Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/weather/sources/{source_id}/models/{model_id}": {
      "get": {
        "tags": [
          "sync"
        ],
        "summary": "Get Sync Weather",
        "description": "Request weather data for a specific Model using the given settings (location, period, weather factors, e.g.).\n\nThis data is then formatted as the requested output format (output unit system and file format) before returning the requested data.\n\n(Please note that as some models are predictive or otherwise restricted in the periods available for requests,\nthat sometimes the 'begin' and 'end' values will be altered to match these restrictions.)\nAn API function that retrieves specific weather data for a specific Weather Model and returns it as the\nrequested output format and units.\n\nArgs:\n    request:        The original request object containing query parameters.\n    source_id:      The Source ID of the Source to request the weather data from.\n    model_id:       The Model ID for the Model to request the weather data from.\n    cleanup_tasks:  A BackgroundTasks object to hold any pending cleanup tasks for when the data request is\n                    finished.\n    ret_args:       A WeatherContentRequestQuery object holding the parameters for the weather data request to\n                    use.\n    fmt_args:       A WeatherFormattingRequestQuery object holding the parameters for the output format and\n                    units to use.\n    accept:         Header type to use for the output file.\n                    Rounded to the most likely value using header_accept_type().\n\nReturns:\n    The weather data in the requested format for the requested parameters.",
        "operationId": "get_sync_weather_weather_sources__source_id__models__model_id__get",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Source Id"
            }
          },
          {
            "name": "model_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Model Id"
            }
          },
          {
            "name": "begin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "From date and time",
              "examples": [
                "2026-08-11 00:00"
              ],
              "title": "Begin"
            },
            "description": "From date and time"
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "To date and time",
              "examples": [
                "2026-08-11 23:59"
              ],
              "title": "End"
            },
            "description": "To date and time"
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "description": "GPS Latitude or RD x-coordinate",
              "examples": [
                52.1
              ],
              "title": "Lat"
            },
            "description": "GPS Latitude or RD x-coordinate"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "description": "GPS Longitude or RD y-coordinate",
              "examples": [
                5.18
              ],
              "title": "Lon"
            },
            "description": "GPS Longitude or RD y-coordinate"
          },
          {
            "name": "factors",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only return these weather factors (default: all factors)",
              "title": "Factors"
            },
            "description": "Only return these weather factors (default: all factors)"
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/OutputUnit",
              "description": "Unit of weather factors",
              "default": "si"
            },
            "description": "Unit of weather factors"
          },
          {
            "name": "response_format",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ResponseFormat",
              "description": "Response format (overrides mime-types from Accept HTTP header)",
              "default": "netcdf4"
            },
            "description": "Response format (overrides mime-types from Accept HTTP header)"
          },
          {
            "name": "accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "title": "Accept"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the requested weather data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No data was found for the given period or file not found."
          },
          "422": {
            "description": "Invalid or missing query parameters."
          }
        }
      }
    },
    "/weather/alarms/knmi": {
      "get": {
        "tags": [
          "alerts"
        ],
        "summary": "Get Alarm",
        "description": "Fetch the WeatherAlarm status for all the provinces from KNMI Weer Alarm and returns the results.\n\nAn API Function that reads the status of the Weer Alarm pages on the KNMI Site and returns them.\n\nReturns:\n    A formatted text containing the current Weather Alert Status for each of the provinces.",
        "operationId": "get_alarm_weather_alarms_knmi_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "prefixItems": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "type": "array",
                    "maxItems": 2,
                    "minItems": 2
                  },
                  "type": "array",
                  "title": "Response Get Alarm Weather Alarms Knmi Get"
                }
              }
            }
          }
        }
      }
    },
    "/weather/sources/{source_id}/models/{model_id}/multiple-locations/": {
      "get": {
        "tags": [
          "sync"
        ],
        "summary": "Get Sync Weather Multi Loc",
        "description": "Request weather data for a specific Model using the given settings.",
        "operationId": "get_sync_weather_multi_loc_weather_sources__source_id__models__model_id__multiple_locations__get",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Source Id"
            }
          },
          {
            "name": "model_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Model Id"
            }
          },
          {
            "name": "begin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "From date and time",
              "examples": [
                "2026-08-11 00:00"
              ],
              "title": "Begin"
            },
            "description": "From date and time"
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "To date and time",
              "examples": [
                "2026-08-11 23:59"
              ],
              "title": "End"
            },
            "description": "To date and time"
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "description": "GPS Latitude or RD x-coordinate",
              "examples": [
                52.1
              ],
              "title": "Lat"
            },
            "description": "GPS Latitude or RD x-coordinate"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "description": "GPS Longitude or RD y-coordinate",
              "examples": [
                5.18
              ],
              "title": "Lon"
            },
            "description": "GPS Longitude or RD y-coordinate"
          },
          {
            "name": "factors",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only return these weather factors (default: all factors)",
              "title": "Factors"
            },
            "description": "Only return these weather factors (default: all factors)"
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/OutputUnit",
              "description": "Unit of weather factors",
              "default": "si"
            },
            "description": "Unit of weather factors"
          },
          {
            "name": "response_format",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ResponseFormat",
              "description": "Response format (overrides mime-types from Accept HTTP header)",
              "default": "netcdf4"
            },
            "description": "Response format (overrides mime-types from Accept HTTP header)"
          },
          {
            "name": "accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "title": "Accept"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the requested weather data.",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "404": {
            "description": "No data was found for the given period or file not found."
          },
          "422": {
            "description": "Invalid or missing query parameters."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "OutputUnit": {
        "type": "string",
        "enum": [
          "si",
          "human",
          "original"
        ],
        "title": "OutputUnit",
        "description": "Enumeration of valid output unit sets for weather data."
      },
      "ResponseFormat": {
        "type": "string",
        "enum": [
          "netcdf4",
          "netcdf3",
          "json",
          "json_dataset",
          "csv"
        ],
        "title": "ResponseFormat",
        "description": "Enumeration of valid output file-formats for weather data responses."
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "WeatherModel": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Model id"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Model name"
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Model version",
            "default": ""
          },
          "url": {
            "type": "string",
            "title": "Url",
            "description": "Model URL",
            "default": ""
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Model description",
            "default": ""
          },
          "predictive": {
            "type": "boolean",
            "title": "Predictive",
            "description": "Predictions or measurements"
          },
          "async_model": {
            "type": "boolean",
            "title": "Async Model",
            "description": "Whether the model should be called asynchronously"
          },
          "time_step_size_minutes": {
            "type": "integer",
            "title": "Time Step Size Minutes",
            "description": "Time between each measurement or prediction"
          },
          "num_time_steps": {
            "type": "integer",
            "title": "Num Time Steps",
            "description": "Number of data points in the result set"
          }
        },
        "type": "object",
        "required": [
          "id",
          "name",
          "predictive",
          "async_model",
          "time_step_size_minutes",
          "num_time_steps"
        ],
        "title": "WeatherModel",
        "description": "Model describing a weather model's metadata and configuration."
      },
      "WeatherSource": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Source id"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Source name"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Url",
            "description": "Source URL"
          },
          "models": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/WeatherModel"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Models",
            "description": "Synchronous models"
          },
          "async_models": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/WeatherModel"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Async Models",
            "description": "Asynchronous models"
          }
        },
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "title": "WeatherSource",
        "description": "Model describing a weather data source and its available models."
      }
    }
  }
}