Guide

Weather Alerts

2016-11-11

“Alerts” are conditions to be checked in a specific location or area when a new forecast cycle becomes available. An alert is said to have been “triggered” if its condition evaluates to true in a given forecast epoch on its defined area. The opposite of triggered is “idle”.

Alerts are defined and owned by individual users, who specify “transports” over which they will be notified of the results of the alert evaluation. These transports are in the form of URI’s with one of a number of supported protocols.

The notification results consist of a list of forecast epochs for which the alert was evaluated and a corresponding “score”, a number from 0 to 1 which represents over how much of the search area the alert condition evaluated to true. Optionally, it may also return GeoJSON data with the exact points that have been sampled.

Alert definitions

Alerts can be defined as JSON or YAML entities. They can have the following properties, many of which are optional.

ID

Element: id [Number|String] (optional)

A user-defined numeric or string ID. It may be used by the creator of the alert to discriminate between multiple alerts going to the same endpoint.

Name

Element: name [String]

A human-readable short name for the alert.

Description

Element: description [String] (optional)

A longer, human-readable description.

Geographic area

Element: where [Object]

A GeoJSON feature collection specifying the search area for the condition. If the condition is true anywhere within the search area, the condition will be triggered.

Condition

Element: condition [String]

The actual condition to evaluate, as an arbitrary expression in the NRPL language. This is a stack-based language which allows the user to enter very complex conditions in a compact manner.

Time extents

Element: epochs|tstamps

An alert is always evaluated over a certain number of forecast epochs, producing a result for each. Epochs can be specified either as relative to the current forecast cycle, or as absolute timestamps.

Relative epochs

Element: epochs [Object] (optional)

Relative epochs are expressed as whole hours, numbered from the most recent quarter day (UTC) in the past.

For example, an alert triggered at 10:32Z will have its zero epoch set to 06:00Z on the same day. An alert triggered at 23:59Z will see 18:00Z as its zero epoch.

The epochs object has up to three properties:

Property Description
from The start of the alert’s period of interest. An integer between 0 and 330, defaults to 0.
until The end of the alert’s period of interest. An integer between 0 and 330, defaults to 0.
step The hourly frequency with which the condition will be checked between epochs.from and epochs.until. An integer between 0 and 330, defaults to 1.

Absolute timestamps

Element: tstamps [Array] (optional)

If epochs is not given, the user may instead give one or more absolute UTC timestamps in ISO-8601 format (e.g., “ 2016-01-03T12:00Z”). The condition will be checked against the specified epochs only. For this to work, the epochs must be within the range of the current forecast—the alert will be inactive if the epochs are more than 330 hours in the future, or more than about six hours in the past.

Notification format

Element: format [String] (optional)

A string with either of the values short (the default) or long.

Notifiers

Element: notifiers [Array]

A list of URIs corresponding to endpoints to be notified when an alert is evaluated.

Status

Element: active [Boolean] (optional)

A boolean to specify whether this alert should be evaluated. The user may keep alert definitions stored in the server without having them evaluated on every new forecast cycle.

Alert formats

Alerts are accepted in JSON or YAML format, with the latter being transformed into JSON during internal processing.

JSON

Example alert:

{
	"id": 6,
	"name": "Precipitation in Vienna",
	"description": "Whether it is raining in Vienna, check at six-hourly intervals for next five days.",
	"where": {
		"type": "FeatureCollection",
		"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
		"features": [
			{ "type": "Feature",
				"properties": {},
				"geometry": {
					"type": "Point",
					"coordinates": [16.3725042,48.2083537]
					}
			}
		]
	},
	"condition": "$APCP not",
	"epochs": {
		"from": 0,
		"until": 120,
		"step": 6
	},
	"active": true,
	"format": "short",
	"notifiers": [
		"https://example.com/alerts/06",
		"xmpp://alerts@example.com/Alert-06"
	]
}

YAML

The same alert as in the previous example, as YAML:

---
id: 6
name: Precipitation in Vienna
description: Whether it is raining in Vienna, check at six-hourly
  intervals for next five days.
where:
  type: FeatureCollection
  crs:
    type: name
    properties:
      name: urn:ogc:def:crs:OGC:1.3:CRS84
  features:
  - type: Feature
    properties: {}
    geometry:
      type: Point
      coordinates:
      - 16.3725042
      - 48.2083537
condition: "$APCP not"
epochs:
  from: 0
  until: 120
  step: 6
active: true
format: short
notifiers:
- https://example.com/alerts/06
- xmpp://alerts@example.com/Alert-06

This other example shows a more complex alert, which checks for temperature and wind being within a given range over a whole (small) country at noon UTC on certain specific dates. The alert will remain inactive until those dates come within the range of the forecast, and will go inactive again once they slip past it.

The coordinates section has been trimmed for brevity. The whole file is available for download (you may also be interested on its JSON equivalent).

---
name: Czech Republic
description: Temperature between 20 and 25 degrees and wind below 5 knots.
where:
  type: FeatureCollection
  crs:
    type: name
    properties:
      name: urn:ogc:def:crs:OGC:1.3:CRS84
  features:
  - type: Feature
    properties:
      NAME: Czech Republic
      ISO_3_CODE: CZE
      ISO_2_CODE: CZ
      AREA: 7727
      NAME_1: Czech Republic
      POP2005: 10191762
      REGION: Europe
      GMI_CNTRY: CZE
      NAME_12: Czech Republic
    geometry:
      type: Polygon
      coordinates:
      - - - 12.093469619750977
          - 50.32419967651367
        - - 12.260000228881836
          - 50.261661529541016
        - - 12.280550003051758
          - 50.186100006103516
        - - 12.329719543457031
          - 50.169708251953125
        - - 12.364720344543457
          - 50.27914810180664
condition: "$TMP 273.15 - dup 20 ge swap 25 le and $UGRD sq $VGRD sq + sqrt 3.6 * 1.852 / 5 le and"
tstamps:
- '2017-06-01T12:00:00.000Z'
- '2017-06-02T12:00:00.000Z'
- '2017-06-03T12:00:00.000Z'
- '2017-06-04T12:00:00.000Z'
- '2017-06-05T12:00:00.000Z'
- '2017-06-06T12:00:00.000Z'
- '2017-06-07T12:00:00.000Z'
active: true
notifiers:
- https://example.com/alerts
- mailto://alerts@example.com?subject=Alert+for+first+week+of+June+2017

Notifications

When an alert is evaluated, its results are sent to each of a list of endpoints that the user defines in the notifiers property. See the endpoints section for more details.

If delivery to one or more of the defined enpoints fails repeatedly, the alert will eventually be set to inactive.

Notification format

Notifications are always JSON objects. “Short” and “long” formats are available, with the latter being more verbose.

Short format

Example:

{
    "name": "Precipitation in Vienna",
    "description": "Whether it is raining in Vienna, check at six-hourly intervals for next five days.",
    "epochs": {
        "2016-10-04T12:00:00.000Z": { "score": 0 },
        "2016-10-04T18:00:00.000Z": { "score": 0 },
        "2016-10-05T00:00:00.000Z": { "score": 1 },
        "2016-10-05T06:00:00.000Z": { "score": 1 },
        "2016-10-05T12:00:00.000Z": { "score": 0 },
        "2016-10-05T18:00:00.000Z": { "score": 0 },
        "2016-10-06T00:00:00.000Z": { "score": 0 },
        "2016-10-06T06:00:00.000Z": { "score": 0.25 },
        "2016-10-06T12:00:00.000Z": { "score": 1 },
        "2016-10-06T18:00:00.000Z": { "score": 0 },
        "2016-10-07T00:00:00.000Z": { "score": 1 },
        "2016-10-07T06:00:00.000Z": { "score": 1 },
        "2016-10-07T12:00:00.000Z": { "score": 1 },
        "2016-10-07T18:00:00.000Z": { "score": 1 },
        "2016-10-08T00:00:00.000Z": { "score": 1 },
        "2016-10-08T06:00:00.000Z": { "score": 0.5 },
        "2016-10-08T12:00:00.000Z": { "score": 0 },
        "2016-10-08T18:00:00.000Z": { "score": 1 },
        "2016-10-09T00:00:00.000Z": { "score": 1 },
        "2016-10-09T06:00:00.000Z": { "score": 1 },
        "2016-10-09T12:00:00.000Z": { "score": 0.5 }
    }
}

The short format object has these properties:

Property Description
id The contents of alert.id, if present.
name The contents of alert.name.
description The contents of alert.description.
epochs A list of epochs, each property is an ISO-8601 timestamp.
epochs[].score The score value for the alert at each epoch.

Long format

Example:

{
    "name": "Precipitation in Vienna",
    "description": "Whether it is raining in Vienna, check at six-hourly intervals for next five days.",
    "epochs": {
        "2016-10-04T12:00:00.000Z": {
            "score": 0,
            "points": {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475582400
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.25,
                                48
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475582400
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.25,
                                48.25
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475582400
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.5,
                                48
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475582400
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.5,
                                48.25
                            ]
                        }
                    }
                ]
            }
        },
        "2016-10-04T18:00:00.000Z": {
            "score": 0,
            "points": {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475604000
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.25,
                                48
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475604000
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.25,
                                48.25
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475604000
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.5,
                                48
                            ]
                        }
                    },
                    {
                        "type": "Feature",
                        "properties": {
                            "value": false,
                            "epoch": 1475604000
                        },
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                16.5,
                                48.25
                            ]
                        }
                    }
                ]
            }
        }
    }
}

The long format object has all the properties of the short format, plus a list of points at which the alert condition was evaluated, as a GeoJSON feature collection.

Property Description
id The contents of alert.id, if present.
name The contents of alert.name.
description The contents of alert.description.
epochs A list of epochs, each property is an ISO-8601 timestamp.
epochs[].score The score value for the alert at each epoch.
epochs[].points GeoJSON feature collection.

The feature collection consists of Point features, each having two properties:

Property Description
value The result of the alert condition evaluation at this point and epoch.
epoch The epoch, as a Unix timestamp.

Endpoints

HTTP / HTTPS

URI protocol: http:// or https://

These endpoints will be sent an HTTP POST request, with Content-Type: application/json. The body of the request will be a JSON object as specified in the format section.

The request’s origin IP will resolve to wxt.navlost.eu and the User-Agent header should contain the string WXT Alerts. The user may wish to only process connections that comply with those parameters for some added security.

XMPP

URI protocol: xmpp://

An XMPP endpoint will receive a message from xmpp://wxt@navlost.eu containing a stanza with a JSON message body, as described in the format section.

MAILTO

URI protocol: mailto://

E-mail endpoints will receive a message from mailto://wxt@navlost.eu containing a JSON message body, as described in the format section.

← Data elements Introduction to NRPL →

© 2016 Aaltronav s.r.o.