openapi: 3.0.3 info: title: Weather Service API version: 2.0.0 description: |- This OpenAPI specification describes the REST API for the DIPUL Weather Service provided by the German Air Traffic Control (DFS - Deutsche Flugsicherung GmbH). This API provides access to a variety of meteorological data, including air pressure, temperature, wind, rain and snow precipitation, cloud cover, and humidity with forecasts for up to 24 hours. The weather data is available for the areas of Federal Republic of Germany, Austria, Switzerland, Denmark, Belgium, the Netherlands and parts of the neigbouring countries. The underlying weather data is sourced from the high-resolution ICON-D2 forecast model provided by the German Meteorological Service (DWD - Deutscher Wetterdienst). This model offers a ~2 km horizontal grid resolution and is updated in 3 hour intervals, enabling detailed and frequently refreshed forecasts. --- Revision History: 2.0.0 - 20.03.2025 - First public release. 1.0.0 - 30.01.2023 - First release. The latest revision of this document can be found at ---- **DFS Deutsche Flugsicherung GmbH**\ Unternehmenszentrale\ Am DFS-Campus 10\ 63225 Langen\ Tel.: +49 - (0)6103 - 707 - 0 This document © 2025 by [DFS Deutsche Flugsicherung GmbH](https://dfs.de) is licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/?ref=chooser-v1) This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, even for commercial purposes. servers: - url: https://utm-service.dfs.de description: Production base URL tags: - name: Weather endpoint description: Requests weather information. paths: /api/weather/v1/weather: post: tags: - Weather endpoint summary: Requests weather information description: |- This endpoint provides following weather data: * Wind speed and direction (for various heights) * QNH value (ISA-based barometric pressure at sea level) * Temperature (for various heights) * Rain precipitation * Snow precipitation * Cloud cover (total or for various heights) * Air humidity (for various heights) The heights for some weather attributes are available in the range between 0 and 250 meter above ground level, typically in 50 meter increments. Note that the minimum available height may vary for different weather attributes. operationId: weather requestBody: content: application/json: schema: $ref: '#/components/schemas/WeatherRequest' examples: default: description: |- Sends a request to retrieve all weather parameters for the specified geographic locations. value: positions: - latitude: 50.0073197 longitude: 8.6554764 qnh: {} temperature: {} wind: {} rainPrecipitation: {} snowPrecipitation: {} cloudCover: {} totalCloudCover: {} airHumidity: {} multiple heights: description: |- Requests temperature values in degrees Celsius at various heights for the specified geographic location. value: positions: - latitude: 50.0073197 longitude: 8.6554764 temperature: unit: C heights: - reference: AGL unit: m value: 50 - reference: AGL unit: m value: 75 - reference: AGL unit: m value: 210 multiple positions: description: |- Requests temperature values in degrees Celsius for multiple specified geographic location. value: positions: - latitude: 50.0073197 longitude: 8.13572 temperature: {} - latitude: 50.457521 longitude: 8.6554764 temperature: {} - latitude: 49.813145 longitude: 9.231879 temperature: {} explicit: description: |- Sends a very explicit request to retrieve maximum amount of weather data at multiple positions. value: positions: - latitude: 50.0073197 longitude: 8.13572 qnh: unit: Pa temperature: unit: C heights: - reference: AGL unit: m value: 2 - reference: AGL unit: m value: 75 - reference: AGL unit: m value: 210 wind: unit: m/s heights: - reference: AGL unit: m value: 15 - reference: AGL unit: m value: 130 rainPrecipitation: unit: mm snowPrecipitation: unit: cm cloudCover: unit: '%' heights: - reference: AGL unit: m value: 130 - reference: AGL unit: m value: 222 - reference: AGL unit: m value: 250 totalCloudCover: unit: '%' airHumidity: unit: '%' heights: - reference: AGL unit: m value: 2 - reference: AGL unit: m value: 123 - latitude: 50.457521 longitude: 8.6554764 temperature: unit: F heights: - reference: AGL unit: m value: 2 rainPrecipitation: unit: mm - latitude: 49.813145 longitude: 9.231879 temperature: unit: K heights: - reference: AGL unit: m value: 2 required: true responses: '200': description: Weather data at given parameters content: application/json: schema: $ref: '#/components/schemas/WeatherResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' components: schemas: WeatherRequest: type: object required: - positions description: |- Weather data requests always require a geographic location. Forecasts up to 24 hours in advance are available using additional parameters. Some weather attributes also allow specifying a height. properties: positions: maxItems: 10 minItems: 1 type: array items: $ref: '#/components/schemas/PositionWeatherRequest' PositionWeatherRequest: type: object required: - latitude - longitude description: Parameters for weather data request. properties: latitude: maximum: 58.01 minimum: 43.19 type: number description: |- Latitude and longitude units are expressed as decimal degrees (DD). The coordinate reference system used is WGS84 datum. Requests are limited to the bounding box defined by the minimum and maximum latitude and longitude provided. While a request may fall within this overall area, note that weather data is not available for every point within the bounding box. format: double example: 50.0073197 longitude: maximum: 20.19 minimum: -3.87 type: number description: |- Latitude and longitude units are expressed as decimal degrees (DD). The coordinate reference system used is WGS84 datum. Requests are limited to the bounding box defined by the minimum and maximum latitude and longitude provided. While a request may fall within this overall area, note that weather data is not available for every point within the bounding box. format: double example: 8.6554764 forecasts: maxItems: 24 type: array items: type: string format: date-time example: '2025-01-01T13:00:00Z' description: |- A list of timestamps for which the forecasts are being requested. If this list is omitted, the nearest full hour is used. Accepted timestamps are between the last full hour and 24 hours into the future. For best results, provide timestamps corresponding to full hours. Using timestamps between full hours will result in linearly interpolated forecast data, which may be less accurate. It's recommended to always use UTC time standard. Using times in other timezones is accepted and will be handled properly. The timestamp value in the response object will however always be in UTC. qnh: $ref: '#/components/schemas/QNH' temperature: $ref: '#/components/schemas/Temperature' wind: $ref: '#/components/schemas/Wind' rainPrecipitation: $ref: '#/components/schemas/RainPrecipitation' snowPrecipitation: $ref: '#/components/schemas/SnowPrecipitation' cloudCover: $ref: '#/components/schemas/CloudCover' totalCloudCover: $ref: '#/components/schemas/TotalCloudCover' airHumidity: $ref: '#/components/schemas/AirHumidity' QNH: type: object description: |- QNH is a pressure setting used in aircraft altimeters. It's the barometric pressure at sea level that, when set on altimeter, will display true elevation above sea level at that particular location. QNH isn't the actual sea level pressure. QNH is derived from the pressure measured at a specific location and elevation, using International Standard Atmosphere (ISA) model of the atmosphere (e.g., assuming a temperature of 15°C). Real-world conditions may vary. properties: unit: type: string example: Pa enum: - Pa QNHResponse: required: - height - unit - value type: object properties: unit: type: string example: Pa enum: - Pa height: $ref: '#/components/schemas/QnhHeight' value: type: number format: double QnhHeight: type: object description: Definition of 0 meter height for the mean sea level. properties: unit: type: string enum: - m description: m - meter value: maximum: 0 minimum: 0 type: integer format: int32 reference: type: string enum: - MSL description: MSL - Mean Sea Level Temperature: type: object description: Air temperature at specific height. properties: unit: type: string example: C enum: - C - F - K description: |- C - degree Celsius F - degree Fahrenheit K - degree Kelvin heights: type: array items: $ref: '#/components/schemas/TemperatureHeight' TemperatureHeight: type: object description: |- Height for which the air temperature is requested or provided. While value of height can be specified between 2 and 250 meters, forecast model provides only discrete heights: [2, 50, 100, 150, 200, 250]. Calculations between these heights involve linear interpolation and the results may be less accurate. properties: unit: type: string enum: - m description: m - meter value: maximum: 250 minimum: 2 type: integer format: int32 reference: type: string enum: - AGL description: AGL - Height Above Ground Level TemperatureResponse: required: - height - unit - value type: object properties: unit: type: string example: C enum: - C - F - K description: |- C - degree Celsius F - degree Fahrenheit K - degree Kelvin height: $ref: '#/components/schemas/TemperatureHeight' value: type: number format: float Wind: type: object description: Wind speed and direction at specific height. properties: unit: type: string example: m/s enum: - m/s description: m/s - meters per second heights: type: array items: $ref: '#/components/schemas/WindHeight' WindHeight: type: object description: |- Wind speed at given height. While value of height can be specified between 10 and 250 meters, forecasts model provides only for discrete heights: [10, 50, 100, 150, 200, 250]. Calculations between these heights involve linear interpolation and the results may be less accurate. properties: unit: type: string enum: - m description: m - meter value: maximum: 250 minimum: 10 type: integer format: int32 reference: type: string enum: - AGL description: AGL - Height Above Ground Level WindResponse: type: object description: |- The response will deliver height and speed of the wind, and a unit vector in two-dimensional horizontal plane for wind direction. Wind direction, expressed as vector, points from the origin of the wind and is decomposed into Cartesian components, East-West (u component), and North-South (v component). Wind direction, expressed as angle in unit of degrees (0°-360°), is the direction from which the wind is blowing, measured clockwise from true north. To calculate the angle from the u and v components use: ``` angle = atan2(u, v) × (180/π) ``` required: - height - unit - uComponent - vComponent properties: unit: type: string example: m/s enum: - m/s description: m/s - meters per second height: $ref: '#/components/schemas/WindHeight' windSpeedGust: type: number description: Only available for height 10 meter AGL. format: double uComponent: type: number format: double description: Horizontal (East-West) speed component. vComponent: type: number format: double description: Vertical (North-South) speed component. RainPrecipitation: type: object description: |- Amount of released water (rain) from the atmosphere that can be observed on the ground. properties: unit: type: string example: mm enum: - kg - mm description: |- mm - Millimeters per hour kg - Kilograms per hour The units `kg` and `mm` are interchangeable. Same value with different units denote the same amount of water. RainPrecipitationResponse: type: object required: - height - unit - value properties: unit: type: string example: mm enum: - kg - mm description: |- mm - Millimeters per hour kg - Kilograms per hour The units `kg` and `mm` are interchangeable. Same value with different units denote the same amount of water. height: $ref: '#/components/schemas/GroundHeight' value: type: number format: float SnowPrecipitation: type: object description: |- Amount of released snow from the atmosphere that can be observed on the ground. properties: unit: type: string example: cm enum: - kg - mm - cm description: |- mm - Millimeters per hour kg - Kilograms per hour cm - Centimeters per hour The units `kg` and `mm` represent the water equivalent. They are interchangeable. Same value with different units denote the same water equivalent. `cm` is the unit for the amount of estimated fresh snow and is equal to 10 times the water equivalent. SnowPrecipitationResponse: type: object required: - height - unit - value properties: unit: type: string example: cm enum: - kg - mm - cm description: |- mm - Millimeters per hour kg - Kilograms per hour cm - Centimeters per hour The units `kg` and `mm` represent the water equivalent. They are interchangeable. Same value with different units denote the same water equivalent. `cm` is the unit for the amount of estimated fresh snow and is equal to 10 times the water equivalent. height: $ref: '#/components/schemas/GroundHeight' value: type: number format: float CloudCover: type: object description: |- Cloud cover indicates the portion of the sky obscured by the clouds. As clouds form in different heights (or layers) due to varying atmospheric conditions, cloud cover is specified for individual layers. properties: unit: type: string example: '%' enum: - '%' description: '''%'' - percentage' heights: type: array items: $ref: '#/components/schemas/CloudCoverHeight' CloudCoverHeight: type: object description: |- Cloud coverage at given height. While value of height can be specified between 50 and 250 meters, forecast model provides only discrete heights: [50, 100, 150, 200, 250]. Calculations between these heights involve linear interpolation and the results may be less accurate. properties: unit: type: string enum: - m value: maximum: 250 minimum: 50 type: integer format: int32 reference: type: string enum: - AGL description: AGL - Height Above Ground Level CloudCoverResponse: required: - height - unit - value type: object properties: unit: type: string example: '%' enum: - '%' height: $ref: '#/components/schemas/CloudCoverHeight' value: type: number format: float TotalCloudCover: type: object properties: unit: type: string example: '%' enum: - '%' description: '`%` - percentage of celestial dome obscured' description: |- Total cloud cover indicates the portion of the celestial dome obscured by clouds accross all layers of the atmosphere. TotalCloudCoverResponse: required: - height - unit - value type: object properties: unit: type: string example: '%' enum: - '%' description: '`%` - percentage of celestial dome obscured' height: $ref: '#/components/schemas/GroundHeight' value: type: number format: float AirHumidity: type: object description: |- Air humidity represent the amount of water vapor present in the Earth's atmosphere. properties: unit: type: string example: '%' enum: - '%' description: '% - percentage of water vapor in the atmosphere' heights: type: array items: $ref: '#/components/schemas/AirHumidityHeight' AirHumidityResponse: type: object required: - height - unit - value properties: unit: type: string example: '%' enum: - '%' description: '% - percentage of water vapor in the atmosphere' height: $ref: '#/components/schemas/AirHumidityHeight' value: type: number format: float AirHumidityHeight: type: object description: |- Air humidity value at given height. While value of height can be specified between 50 and 250 meters, forecast model provides only only for discrete heights: [50, 100, 150, 200, 250]. Calculations between these heights involve linear interpolation and the results may be less accurate. properties: unit: type: string enum: - m value: maximum: 250 minimum: 2 type: integer format: int32 reference: type: string enum: - AGL description: AGL - Height Above Ground Level GroundHeight: type: object properties: unit: type: string enum: - m value: maximum: 0 minimum: 0 type: integer format: int32 reference: type: string enum: - AGL description: AGL - Height Above Ground Level description: Definition of 0 meter height for the ground level. WeatherResponse: required: - calculationTime - positions type: object properties: calculationTime: type: string description: |- The weather model is calculated in 3 hour intervals. This is the timestamp of the model run used to provide the weather data. format: date-time positions: type: array items: $ref: '#/components/schemas/PositionWeatherResponse' PositionWeatherResponse: type: object required: - latitude - longitude properties: latitude: type: number format: double longitude: type: number format: double forecasts: type: array items: $ref: '#/components/schemas/ForecastResponse' status: $ref: '#/components/schemas/Status' description: |- Latitude and longitude units are expressed as decimal degrees (DD). The coordinate reference system used is WGS84 datum. ForecastResponse: type: object required: - timestamp properties: timestamp: type: string description: |- Timestamp for which the forecast was requested. Timestamp will always be in UTC. format: date-time qnh: $ref: '#/components/schemas/QNHResponse' temperature: type: array items: $ref: '#/components/schemas/TemperatureResponse' wind: type: array items: $ref: '#/components/schemas/WindResponse' airHumidity: type: array items: $ref: '#/components/schemas/AirHumidityResponse' rainPrecipitation: $ref: '#/components/schemas/RainPrecipitationResponse' snowPrecipitation: $ref: '#/components/schemas/SnowPrecipitationResponse' cloudCover: type: array items: $ref: '#/components/schemas/CloudCoverResponse' totalCloudCover: $ref: '#/components/schemas/TotalCloudCoverResponse' Status: type: object properties: message: type: string failedForecasts: type: array description: No weather data is available for given timestamps. items: type: string format: date-time ErrorResponse: type: object properties: errorType: type: string enum: - missingParam - invalidParam - unimplemented - invalidJson - unknownError errorMessage: type: string InternalErrorResponse: type: object properties: errorType: type: string enum: - internal - data errorMessage: type: string