Radar Precipitation Forecast API
Powered by DTN

Overview

DTN Radar Precipitation Forecast API provides time series with short-term precipitation forecasts, based on radar data via https://precipitation-forecast.weather.mg/search. A forecast can be requested that is either representative of a specific location, or an area smaller than 40x40 km (via the bounding box).

The time series contains a data set, including the latest observed radar-derived precipitation intensity value combined with a 3-hourly forecast. The time series has a temporal resolution of between 5 and 15 minutes, depending on the temporal resolution of the original source data.

Data sources used for the Radar Precipitation Forecast API

Country Spatial resolution Temporal resolution
Germany 250m 5 min
Belgium 1km 15 min
Netherlands 1km 5 min
UK/Ireland 1km 5 min
Spain 2km 10 min
France 1km 5 min
Switzerland 1km 5 min
Scandinavia 2km 15 min
Poland 2km 10 min
Australia 2km 10 min

Value proposition of the Radar Precipitation Forecast API

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

Parameter Value added
Coverage Using different areas / sources.
Sharpness Areas are available in the highest resolution.
Correctness Applying an optimized decluttering algorithm to filter out false radar echoes.
Completeness Adding forecast radar data and precipitation type to core data.
Temporal resolution Enabling a 3-hour forecast time series based on radar data.
Availability Time series via API allows optimal integration to aid decision making.

Use case: Request radar precipitation forecast data for a location

You can request radar precipitation forecast data for a location.

Below table lists the required API endpoint, a URL example, and the HTTP method used.

Api endpoint /search?locatedAt={locatedAt}&fields={fields}&validFrom={validFrom}&validUntil={validUntil}
URL example https://precipitation-forecast.weather.mg/search?validFrom=2018-06-18T14:00:00Z&validUntil= 2018-06-18T15:00:00Z&fields=validPeriod,issuedAt,precipitationType,dataSource,dataType, precipitationAmountInMillimeters,precipitationIntensityInMillimetersPerHour&locatedAt=20.64,68.95
Method GET

Request parameters

To request a radar precipitation forecast for a location, supply the following items in your API call.

Parameter Description Data Type
locatedAt locatedAt This required parameter sets a geographical point (longitude, latitude) following the pattern in the following example: '2.1897,-35.7123'. Longitude should be within the range [-180.0; 180.0], and latitude should be within the range [-90.0; 90.0]. A pair of float numbers, required A pair of float numbers, required
fields fields This required parameter should be supplied with at least one of the required values. Optional values can be omitted altogether. Supported values for the fields parameter are as follows:
  • (Optional) validPeriod.
  • (Optional) dataSource.
  • (Optional) dataType.
  • (Optional) issuedAt.
  • (Optional) precipitationType.
  • precipitationAmountInMillimeters.
  • precipitationIntensityInMillimetersPerHour.
The response returns a comma-separated list of values. Data types vary 		Data types vary
validFrom & validUntil These required parameters set the time range of the precipitation radar forecast. They use the standard ISO 08601 notation, matching the following pattern: '2017-12-12T10:15:30Z'. The following rules apply:
  • validFrom sets the start timestamp value, represents a timestamp in the future, and precedes the validUntil parameter.
  • validUntil sets the end timestamp value and should not exceed the time of the request for more than 3 hours into the future. For example, if the API request is run at '2017-12-12T11:00:00Z', the end timestamp should be within '2017-12-12T14:00:00Z'.
String, required

Sample response

The following is a sample response. 


      {
        "forecasts": [
            {
                "locatedAt": [
                    20.64,
                    68.95
                ],
                "validFrom": "2018-12-05T11:30:00",
                "validUntil": "2018-12-05T11:30:00",
                "issuedAt": "2018-12-05T11:15:00",
                "validPeriod": "PT0S",
                "dataSource": "fcst-radar.mg.sca",
                "dataType": "FORECAST",
                "precipitationType": "DRY",
                "precipitationIntensityInMillimetersPerHour": 0
            },
            …
        ]
    }

Response definitions

Table bellow describes each item in the response

Response item Description Data type
forecast Contains an array of forecast-related elements. Array
forecasts/locatedAt Indicates the location as a longitude and a latitude. Array
forecast/validFrom Indicates the start timestamp of the time range of the forecast in the standard ISO 08601 notation. String
forecast/validUntil Indicates the end timestamp of the time range associated with the forecast in the standard ISO 08601 notation. String
forecasts/ validPeriod Indicates the forecast retrieval interval. Possible time periods are the following:
  • PT0S (PT stands for period of time, and 0S – zero second) retrieves the precipitation intensity at the specific time set
  • PTXM retrieves the forecast data for the numbers of minutes defined within PTXM where X defines the number of minutes for which the precipitation amount is retrieved. Depending on the radar source the period in minutes needs to be 5, 10 or 15 minutes as the minimum frequency of incoming data defines the period that can be queried.
String
forecast/issuedAt Contains the timestamp of the forecast in the standard ISO 08601 notation. String
forecast/dataSource Contains the data source. String
forecast/dataType Contains either of the predefined values:
  • FORECAST.
  • OBSERVATION.
 String
forecast/precipitationType Available radar values are mapped to one of the following values:
  • SNOW.
  • RAIN.
  • RAIN_AND_SNOW.
  • FREEZING_RAIN.
  • SNOW_PELLETS.
  • SNOW_PELLETS_OR_HAIL.
  • HAIL.
  • UNKNOWN.
  • NOT_AVAILABLE.
 String
forecasts/precipitationAmountInMillimeters Contains the amount of precipitation during validPeriod. Integer
forecasts/precipitationIntensityInMillimetersPerHour Contains momentary precipitation intensity on the validFrom timestamp. Integer

Use case: Request radar precipitation forecast data for an area

You can request radar precipitation radar data for an area.

Below table lists the required API endpoint, a URL example, and the HTTP method used.

Api endpoint /search?locatedWithin={locatedWithin}&fields={fields}&validFrom={validFrom}&validUntil={validUntil}
URL example https://precipitation-forecast.weather.mg/search?fields=validPeriod,dataSource,dataType,issuedAt, precipitationType,minPrecipitationAmountInMillimeters,maxPrecipitationAmountInMillimeters, avgPrecipitationAmountInMillimeters,minPrecipitationIntensityInMillimetersPerHour, maxPrecipitationIntensityInMillimetersPerHour,avgPrecipitationIntensityInMillimetersPerHour& validFrom=2018-06-18T14:00:00Z&validUntil=2018-06-18T15:00:00Z&locatedWithin=[20.54,68.9],[20.64,68.95]
Method GET

Request parameters

To request a radar precipitation forecast for an area, supply the following items in your API call.

Parameter Description Data Type
LocatedWithin This required parameter specifies an area using either of the following options:
  • Bounding box
  • GeoJSON polygon
When data is requested by using a bounding box, the bounding box should match the following pattern: [9.42,51.63],[9.31,51.85], where [x,y] are the corner points of the bounding box; x is longitude, y is latitude. Important:
  • Longitude of each point should be within the range [-180.0;180.0], and latitude of each point should be within the range [-90.0;90.0].
  • Both points should be different.
  • Points should not lie on the same abscissa or ordinate.
When data is requested by using a GeoJSON polygon, the polygon should match the following pattern: {"type":"Polygon","coordinates":[[[9.3,51.1],[9.4,51.4],[9.4,51.0],[9.2,51.0],[9.3,51.1]]]}, Where [x,y] are the corner points of the polygon; x is longitude, y is latitude. Important:
  • The minimum number of points is 4.
  • The first and the last point should be the same.
  • Longitude of each point should be within the range [-180.0;180.0], and latitude of each point should be within the range [-90.0;90.0].
  • The polygon should be in the GeoJson geometry format. See GeoJSON format specification.
 Bounding box or Polygon, required
fields This required parameter should be supplied with at least one of the required values. Optional values can be omitted altogether. Supported values for the fields parameter are as follows:
  • (Optional) validPeriod.
  • (Optional) dataSource.
  • (Optional) dataType.
  • (Optional) issuedAt.
  • (Optional) precipitationType.
  • minPrecipitationAmountInMillimeters.
  • maxPrecipitationAmountInMillimeters.
  • avgPrecipitationAmountInMillimeters.
  • minPrecipitationIntensityInMillimetersPerHour.
  • maxPrecipitationIntensityInMillimetersPerHour.
  • avgPrecipitationIntensityInMillimetersPerHour.
 Data types vary, required
validFrom & validUntil These required parameters set the time range of the precipitation radar forecast. They use the standard ISO 08601 notation, matching the following pattern: '2017-12-12T10:15:30Z'. The following rules apply:
  • validFrom sets the start timestamp value, represents a timestamp in the future, and precedes the validUntil parameter.
  • •validUntil sets the end timestamp value and should not exceed the time of the request for more than 3 hours into the future. For example, if the API request is run at '2017-12-12T11:00:00Z', the end timestamp should be within '2017-12-12T14:00:00Z'.
String, required

Sample response

The following is a sample response. 


     {
        "forecasts": [
            {
                "locatedWithin": [
                    [
                        20.54,
                        68.9
                    ],
                    [
                        20.64,
                        68.95
                    ]
                ],
                "validFrom": "2018-06-18T14:00:00",
                "validUntil": "2018-06-18T14:00:00",
                "issuedAt": "2018-06-18T12:30:00",
                "validPeriod": "PT0S",
                "dataSource": "fcst-radar.mg.sca",
                "dataType": "FORECAST",
                "precipitationType": "RAIN",
                "avgPrecipitationIntensityInMillimetersPerHour": 1.45833,
                "minPrecipitationIntensityInMillimetersPerHour": 1.125,
                "maxPrecipitationIntensityInMillimetersPerHour": 1.625
            },
            {
                "locatedWithin": [
                    [
                        20.54,
                        68.9
                    ],
                    [
                        20.64,
                        68.95
                    ]
                ],
                "validFrom": "2018-06-18T14:00:00",
                "validUntil": "2018-06-18T14:15:00",
                "issuedAt": "2018-06-18T12:30:00",
                "validPeriod": "PT15M",
                "dataSource": "fcst-radar.mg.sca",
                "dataType": "FORECAST",
                "precipitationType": "RAIN",
                "avgPrecipitationAmountInMillimeters": 0.36458,
                "minPrecipitationAmountInMillimeters": 0.28125,
                "maxPrecipitationAmountInMillimeters": 0.40625
            },
            {
                "locatedWithin": [
                    [
                        20.54,
                        68.9
                    ],
                    [
                        20.64,
                        68.95
                    ]
                ],
                "validFrom": "2018-06-18T14:15:00",
                "validUntil": "2018-06-18T14:15:00",
                "issuedAt": "2018-06-18T12:30:00",
                "validPeriod": "PT0S",
                "dataSource": "fcst-radar.mg.sca",
                "dataType": "FORECAST",
                "precipitationType": "RAIN",
                "avgPrecipitationIntensityInMillimetersPerHour": 1.57292,
                "minPrecipitationIntensityInMillimetersPerHour": 1.125,
                "maxPrecipitationIntensityInMillimetersPerHour": 2.5
            }
			        ...
        ]
    }

Response definitions

Table bellow describes each item in the response

Response item Description Data type
forecast Contains an array of forecast-related elements. Array
forecasts/locatedWithin Indicates the location as either a bounding box, or a GeoJSON polygon. Array
forecast/validFrom Indicates the start timestamp of the time range of the forecast in the standard ISO 08601 notation. String
forecast/validUntil Indicates the end timestamp of the time range associated with the forecast in the standard ISO 08601 notation. String
forecasts/ validPeriod Indicates the forecast retrieval interval. Possible time periods are the following:
  • PT0S (PT stands for period of time, and 0S – zero second) retrieves the precipitation intensity at the specific time set
  • PTXM retrieves the forecast data for the numbers of minutes defined within PTXM where X defines the number of minutes for which the precipitation amount is retrieved. Depending on the radar source the period in minutes needs to be 5, 10 or 15 minutes as the minimum frequency of incoming data defines the period that can be queried.
String
forecast/issuedAt Contains the timestamp of the forecast in the standard ISO 08601 notation. String
forecast/dataSource Contains the data source. String
forecast/dataType Contains either of the predefined values:
  • FORECAST.
  • OBSERVATION.
 String
forecast/precipitationType Available radar values are mapped to one of the following values:
  • SNOW.
  • RAIN.
  • RAIN_AND_SNOW.
  • FREEZING_RAIN.
  • SNOW_PELLETS.
  • SNOW_PELLETS_OR_HAIL.
  • HAIL.
  • UNKNOWN.
  • NOT_AVAILABLE.
 String
forecasts/precipitationAmountInMillimeters Contains the amount of precipitation during validPeriod. Integer
forecasts/precipitationIntensityInMillimetersPerHour Contains momentary precipitation intensity on the validFrom timestamp. Integer

Error Response

The table below describes the error response format.

Name Data Type Description
status Integer The code representing the nature of the error. See Common Error Reference for more details.
message 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"
     ]
}
...