Forecast API

Overview

DTN Point Forecast API delivers high quality weather forecasts via https://point-forecast.weather.mg/forecast/hourly. The API can be requested for weather stations, or relevant locations / assets / cities.

Data sources used for the Point Forecast API

In providing the Point Forecast API service, DTN does the following:

Uses multiple data sources for observations such as:
- The general World Meteorological Organization (WMO) data set for weather stations world-wide.
- Specific data sets from WMO to ensure additional stations and a higher frequency of measurements are available.
- Country-specific data sets for weather station’s secondary professional networks.
- DTN own network of weather stations in Germany, Switzerland, Liechtenstein, and Luxemburg.
Uses world-leading atmospheric global weather models including ECMWF, GFS/NOAA and UKMO.
Combines global weather model information with hyperlocal model calculations and observations.
Leverages the DTN MOS forecasting system, which applies advanced big-data analytics and calculates the most likely and accurate forecast for every weather station.
Forecasts available parameters for a given point in time over a defined time span (15 days ahead maximum).
Controls forecast quality.

Value proposition of the Point Forecast API

The value proposition of the Point Forecast API is as listed in the following table, which emphasizes where DTN adds value to core data.

Parameter	Value added
Accuracy	High-quality forecast covering many stations.
Reliability	2-years of training ensures the forecast is adjusted to the local observation site.
Skill	Combination of data from several models ensures a high level of skill.
Uncertainty	MG MOS delivers the estimated error in temperature and wind speed forecast.
Spatial resolution	Smart algorithms enable downscaling of MOS to customer locations.
Coverage	MG MOS is complete - even when stations do not report certain parameters the downscaling algorithms deliver a forecast for that parameter. All MOS stations have [BH1] hourly forecasts for all parameters.
Temporal resolution	The hourly resolution, showing the daily cycle, is also present for the long-range forecast, up to 15 days.
Uniqueness	MG MOS contains several unique parameters, like effective cloudiness, weather type, probability of extreme precipitation amount or wind gust.
Frequency	Even when observations are not hourly, MG MOS fills the gaps and delivers a forecast for every hour.

Request URL Builder

Parameters

Parameter listing	Basic	Standard	Industry
Temperature parameters
airTemperatureInCelsius	3-h	1-h	1-h
dewPointTemperatureInCelsius	3-h	1-h	1-h
relativeHumidityInPercent	3-h	1-h	1-h
airTemperatureNearGroundInCelsius	n/a	1-h	1-h
maxAirTemperatureInCelsius	12-h	12-h	12-h
minAirTemperatureInCelsius	12-h	12-h	12-h
feelsLikeTemperatureInCelsius	n/a	1-h	1-h
Temperature error bias		1-h	1-h
Humidex		1-h	1-h
Wind parameters
windSpeedInMeterPerSecond	3-h	1-h	1-h
windDirectionInDegree	3-h	1-h	1-h
maxWindGustInMeterPerSecond	n/a	1-h	1-h
Average wind speed		24-h	24-h
windSpeedErrorInKnots		1-h	1-h
Precipitation and weather code parameters
weathercodeTraditional	3-h	1-h	1-h
pastWeatherCode	6-h	6-h	6-h
Weathercode/Icon-Mapping 12-h
freshSnowfallInCentimeter	n/a	24-h	24-h
snowDepthInCentimeter	n/a	12-h	12-h
precipitationAmountInMillimeter PTxH	12-h	1-h	1-h
precipitationProbabilityInPercent PTxH	12-h	1-h	1-h
snowCertainAboveHeightInMeter	n/a	1-h	1-h
Cloud, radiation and sunshine parameters
sunshineDurationInMinutes PT24H	24-h	24-h	24-h
sunshineDurationInMinutes PT1H	n/a	1-h	1-h
totalCloudCoverInOcta	n/a	1-h	1-h
effectiveCloudCoverInOcta PT0S	3-h	1-h	1-h
globalRadiationInJoulePerSquareCentimeter	n/a	1-h	1-h
averageGlobalRadiationInWattPerSquareMeter	n/a	1-h	1-h
Daily sum global radiation	n/a	24-h	24-h
evaporationPenmanInMillimeter	n/a	24-h	24-h
UV index, assuming no clouds	n/a	1-h	1-h
UV index considering clouds	n/a	1-h	1-h
Other parameters
visibilityInMeter	n/a	1-h	1-h
airPressureAtSeaLevelInHectoPascal	n/a	1-h	1-h

Forecast data is available via packages also including observation data. The different packages include the following forecast data:

	Consumer basic	Consumer standard	Consumer premium	Enterprise basic	Enterprise standard	Enterprise premium
Daily forecast summary	2 days	5 days	15 days	2 days	5 days	15 days
Hourly forecasts		5 days	15 days	2 days	5 days	15 days
Basic parameters	✔	✔	✔	✔	✔	✔
Standard parameters		✔	✔	✔	✔	✔
Industry parameters						✔
License	Publisher	Publisher	Publisher	End user	End user	End user

Station Metadata

When requesting for forecast using locatedAt, adding "meteoGroupStationId" in the "fields" parameter will include a stationId information together with forecast data in the response

Sample Request:

                    https://point-forecast.weather.mg/forecast/hourly?fields=maxAirTemperatureInCelsius,meteoGroupStationId&locatedAt=6.669,53.58&validPeriod=PT24H&validFrom=2021-04-11T12:00:00Z&validUntil=2021-04-12T12:00:00Z

Sample Response:

                    {
   "forecasts":[
      {
         "locatedAt":[
            6.669,
            53.58
         ],
         "meteoGroupStationId":"3010113",
         "validFrom":"2021-04-10T14:00:00+02:00",
         "validUntil":"2021-04-11T14:00:00+02:00",
         "validPeriod":"PT24H",
         "maxAirTemperatureInCelsius":7.8
      },
      {
         "locatedAt":[
            6.669,
            53.58
         ],
         "meteoGroupStationId":"3010113",
         "validFrom":"2021-04-10T20:00:00+02:00",
         "validUntil":"2021-04-11T20:00:00+02:00",
         "validPeriod":"PT24H",
         "maxAirTemperatureInCelsius":7.3
      },
      {
         "locatedAt":[
            6.669,
            53.58
         ],
         "meteoGroupStationId":"3010113",
         "validFrom":"2021-04-11T02:00:00+02:00",
         "validUntil":"2021-04-12T02:00:00+02:00",
         "validPeriod":"PT24H",
         "maxAirTemperatureInCelsius":7.2
      },
      {
         "locatedAt":[
            6.669,
            53.58
         ],
         "meteoGroupStationId":"3010113",
         "validFrom":"2021-04-11T08:00:00+02:00",
         "validUntil":"2021-04-12T08:00:00+02:00",
         "validPeriod":"PT24H",
         "maxAirTemperatureInCelsius":7.3
      },
      {
         "locatedAt":[
            6.669,
            53.58
         ],
         "meteoGroupStationId":"3010113",
         "validFrom":"2021-04-11T14:00:00+02:00",
         "validUntil":"2021-04-12T14:00:00+02:00",
         "validPeriod":"PT24H",
         "maxAirTemperatureInCelsius":7.7
      }
   ]
}

Formatting

A sample request using the point-forecast API looks like this:

https://point-forecast.weather.mg/forecast/hourly?locatedAt=13.2,52.4&validPeriod=PT0S&fields=airTemperatureInCelsius

The above request will return forecasted air termperature for the city of Berlin, Germany, over the next 3 hours three hours from the time the request was received.

The returned data will be formatted in JSON, and will look like this:

{
      "forecasts": [
        {
          "locatedAt": [
            13.2,
            52.4
          ],
          "validUntil": "2017-03-22T15:00:00+01:00",
          "airTemperatureInCelsius": 11.1,
          "validFrom": "2017-03-22T15:00:00+01:00",
          "validPeriod": "PT0S"
        },
        {
          "locatedAt": [
            13.2,
            52.4
          ],
          "validUntil": "2017-03-22T16:00:00+01:00",
          "airTemperatureInCelsius": 10.8,
          "validFrom": "2017-03-22T16:00:00+01:00",
          "validPeriod": "PT0S"
        },
        {
          "locatedAt": [
            13.2,
            52.4
          ],
          "validUntil": "2017-03-22T17:00:00+01:00",
          "airTemperatureInCelsius": 10.3,
          "validFrom": "2017-03-22T17:00:00+01:00",
          "validPeriod": "PT0S"
        }
      ]
    }

Error Response

The table below describes the error response format.

Name	Data Type	Description
statusCode	Integer	The code representing the nature of the error. See Common Error Reference for more details.
errorMessage	String	Message correlating to the standard status code.
errors	Object	An object containing the fields that violated the constraints. This object uses the field name as the key and an array of error messages for that violated field as the value. If only one constraint is violated, then the value will be an array with one String inside it. Example: `... "errors": { "locatedAt": [ "Requested point or area is outside of area covered by the service. Please try another location" ] } ...`
path	String	Relative path of the URL requested.
timestamp	String	Response date time in ISO 8601 format.
traceId	String	Unique reference ID for the request. Useful for requesting support and tracing error requests.

Nitty-Gritty

For more detailed information on this API, check us out on Bitbucket.

Point-Forecast API