Weather Triggers

You can use simple syntax and a few API methods to create triggers which will fire on an occurrence of the selected weather conditions (temperature, humidity, pressure, etc.) in a specified period of time. For example, if you are interested in the forthcoming frosts or the probability of a wind speed increase in a certain place, you can obtain this information with the help of our new tool. More detailed description about working with the service is given below.

If the trigger's conditions are met, our service will generate an alert. In order to receive this alert you need to poll the service with the specified time interval. We plan to add push notifications and new data sources to this product's functionality in the nearest future.

Three simple steps for working with Weather Triggers API:

  1. Create an account in members area and receive a key to access API.
  2. Create the trigger with the necessary conditions for temperature, pressure, humidity, wind speed, wind direction and clouds.
  3. Poll our service and receive information about an occurrence or a forecast of the upcoming events in which you are interested.

Weather Triggers API basic methods

Minimal prerequisites to start working with our service: create a trigger and receive a list of the current alerts.

[POST] /triggers

This method is used to create a trigger with the necessary conditions and the indication of an interval for observations.

URL Example

http://api.openweathermap.org/data/3.0/triggers
Request Parameters 
                    
{
   "time_period":{
      "start":{
         "expression":"after",
         "amount":132000000
      },
      "end":{
         "expression":"after",
         "amount":432000000
      }
   },
   "conditions":[
      {
         "name":"temp",
         "expression":"$gt",
         "amount":299
      }
   ],
   "area":[
      {
         "type":"Point",
         "coordinates":[
            53,
            37
         ]
      }
   ]
}
API Response 
                    
{
   "__v":0,
   "_id":"585268b72516b90010058184",
   "alerts":{

   },
   "area":[
      {
         "type":"Point",
         "_id":"585268b72516b90010058185",
         "coordinates":[
            53,
            37
         ]
      }
   ],
   "conditions":[
      {
         "name":"temp",
         "expression":"$gt",
         "amount":299,
         "_id":"585268b72516b90010058186"
      }
   ],
   "time_period":{
      "end":{
         "expression":"after",
         "amount":432000000
      },
      "start":{
         "expression":"after",
         "amount":132000000
      }
   }
}

A full description of the returned data structure and the list of parameters can be found here.

Headers: Content-Type: application/json

[GET] /triggers/{:id}

This method is used to get all information about a trigger, including the current alerts. Information about an occurence of the expected events is in an alert's nested structure. The trigger calls a separate method for receiving history notifications.

URL Example

http://api.openweathermap.org/data/3.0/triggers/5852816a9aaacb00153134a3 
                
{
     "_id":"5852816a9aaacb00153134a3",
     "__v":0,
     "alerts":{
        "8b48b2cd21c23d2894466caccba1ed1f":{
           "conditions":[
              {
                 "current_value":{
                    "min":263.576,
                    "max":263.576
                 },
                 "condition":{
                    "name":"temp",
                    "expression":"$lt",
                    "amount":273,
                    "_id":"5852816a9aaacb00153134a5"
                 }
              }
           ],
           "last_update":1481802090232,
           "date":1482181200000,
           "coordinates":{
              "lon":37,
              "lat":53
           }
        }
     },
     "area":[
        {
           "type":"Point",
           "_id":"5852816a9aaacb00153134a4",
           "coordinates":[
              37,
              53
           ]
        }
     ],
     "conditions":[
        {
           "name":"temp",
           "expression":"$lt",
           "amount":273,
           "_id":"5852816a9aaacb00153134a5"
        }
     ],
     "time_period":{
        "end":{
           "amount":432000000,
           "expression":"after"
        },
        "start":{
           "amount":132000000,
           "expression":"after"
        }
     }
  }

A full description of the returned data structure and the list of parameters can be found here.

Additional features of Weather Triggers API

Allows you to get a list of all triggers, change and remove them, receive and manage alerts history.

[GET] /triggers

The method is used to get a list of all triggers (with the current alerts) which are connected to your account.

URL Example

http://api.openweathermap.org/data/3.0/triggers 
                
[
   {
      "_id":"585268b72516b90010058184",
      "__v":0,
      "alerts":{

      },
      "area":[
         {
            "type":"Point",
            "_id":"585268b72516b90010058185",
            "coordinates":[
               53,
               37
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$gt",
            "amount":299,
            "_id":"585268b72516b90010058186"
         }
      ],
      "time_period":{
         "end":{
            "expression":"after",
            "amount":432000000
         },
         "start":{
            "expression":"after",
            "amount":132000000
         }
      }
   },
   {
      "_id":"585280edbe54110025ea52bb",
      "__v":0,
      "alerts":{

      },
      "area":[
         {
            "type":"Point",
            "_id":"585280edbe54110025ea52bc",
            "coordinates":[
               53,
               37
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$lt",
            "amount":273,
            "_id":"585280edbe54110025ea52bd"
         }
      ],
      "time_period":{
         "end":{
            "amount":432000000,
            "expression":"after"
         },
         "start":{
            "amount":132000000,
            "expression":"after"
         }
      }
   },
   {
      "_id":"5852816a9aaacb00153134a3",
      "__v":0,
      "alerts":{
         "8b48b2cd21c23d2894466caccba1ed1f":{
            "conditions":[
               {
                  "current_value":{
                     "min":263.576,
                     "max":263.576
                  },
                  "condition":{
                     "name":"temp",
                     "expression":"$lt",
                     "amount":273,
                     "_id":"5852816a9aaacb00153134a5"
                  }
               }
            ],
            "last_update":1481802090232,
            "date":1482181200000,
            "coordinates":{
               "lon":37,
               "lat":53
            }
         }
      },
      "area":[
         {
            "type":"Point",
            "_id":"5852816a9aaacb00153134a4",
            "coordinates":[
               37,
               53
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$lt",
            "amount":273,
            "_id":"5852816a9aaacb00153134a5"
         }
      ],
      "time_period":{
         "end":{
            "amount":432000000,
            "expression":"after"
         },
         "start":{
            "amount":132000000,
            "expression":"after"
         }
      }
   }
]

A full description of the returned data structure and the list of parameters can be found here.

[PUT] /triggers/{:id}

This method is used to change a trigger's parameters.

IMPORTANT! If the trigger is changed, all related current alerts will be removed.

URL Example

http://api.openweathermap.org/data/3.0/triggers/585280edbe54110025ea52bb
Request Parameters 
                
{
   "time_period":{
      "start":{
         "expression":"after",
         "amount":132000000
      },
      "end":{
         "expression":"after",
         "amount":132000000
      }
   },
   "conditions":[
      {
         "name":"temp",
         "expression":"$lt",
         "amount":270
      }
   ],
   "area":[
      {
         "type":"Point",
         "coordinates":[
            53,
            37
         ]
      }
   ]
}
API Response 
                
{
   "_id":"585268b72516b90010058184",
   "__v":1,
   "alerts":{

   },
   "area":[
      {
         "type":"Point",
         "_id":"58528903d083a2001b7cb428",
         "coordinates":[
            53,
            37
         ]
      }
   ],
   "conditions":[
      {
         "name":"temp",
         "expression":"$lt",
         "amount":270,
         "_id":"58528903d083a2001b7cb427"
      }
   ],
   "time_period":{
      "start":{
         "expression":"after",
         "amount":132000000
      },
      "end":{
         "expression":"after",
         "amount":132000000
      }
   }
}

A full description of the returned data structure and the list of parameters can be found here.

Headers: Content-Type: application/json

[DELETE] /triggers/{:id}

This method is used to remove a trigger from your account. In case of successful removal the service will return an HTTP-code 204 (Successful answer).

IMPORTANT! Along with the trigger all of its alerts (current and past) will also be removed and they couldn't be restored.

URL Example

http://api.openweathermap.org/data/3.0/triggers/585268b72516b90010058184

[GET] /triggers/{:id}/history

This method is used to get a list of historical alerts which were generated by the specified trigger, but now become irrelevant.

URL Example

http://api.openweathermap.org/data/3.0/triggers/5852816a9aaacb00153134a3/history

[GET] /triggers/{:trigger_id}/history/{:alert_id}

This method is used to get information about the specific alert in the trigger's history. You need to pass the trigger's and the alert's ids to the query.

URL Example

http://api.openweathermap.org/data/3.0/triggers/58528.../history/671e2... 
                 
[
   {
      "_id":"585268b72516b90010058184",
      "__v":0,
      "alerts":{

      },
      "area":[
         {
            "type":"Point",
            "_id":"585268b72516b90010058185",
            "coordinates":[
               53,
               37
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$gt",
            "amount":299,
            "_id":"585268b72516b90010058186"
         }
      ],
      "time_period":{
         "end":{
            "expression":"after",
            "amount":432000000
         },
         "start":{
            "expression":"after",
            "amount":132000000
         }
      }
   },
   {
      "_id":"585280edbe54110025ea52bb",
      "__v":0,
      "alerts":{

      },
      "area":[
         {
            "type":"Point",
            "_id":"585280edbe54110025ea52bc",
            "coordinates":[
               53,
               37
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$lt",
            "amount":273,
            "_id":"585280edbe54110025ea52bd"
         }
      ],
      "time_period":{
         "end":{
            "amount":432000000,
            "expression":"after"
         },
         "start":{
            "amount":132000000,
            "expression":"after"
         }
      }
   },
   {
      "_id":"5852816a9aaacb00153134a3",
      "__v":0,
      "alerts":{
         "8b48b2cd21c23d2894466caccba1ed1f":{
            "conditions":[
               {
                  "current_value":{
                     "min":263.576,
                     "max":263.576
                  },
                  "condition":{
                     "name":"temp",
                     "expression":"$lt",
                     "amount":273,
                     "_id":"5852816a9aaacb00153134a5"
                  }
               }
            ],
            "last_update":1481802090232,
            "date":1482181200000,
            "coordinates":{
               "lon":37,
               "lat":53
            }
         }
      },
      "area":[
         {
            "type":"Point",
            "_id":"5852816a9aaacb00153134a4",
            "coordinates":[
               37,
               53
            ]
         }
      ],
      "conditions":[
         {
            "name":"temp",
            "expression":"$lt",
            "amount":273,
            "_id":"5852816a9aaacb00153134a5"
         }
      ],
      "time_period":{
         "end":{
            "amount":432000000,
            "expression":"after"
         },
         "start":{
            "amount":132000000,
            "expression":"after"
         }
      }
   }
]

[DELETE] /triggers/{:trigger_id}/history/{:alert_id}

This method is used to remove a specific alert from a trigger's history. In case of successful removal service will return an HTTP-code 204 (Successful answer).

URL Example

http://api.openweathermap.org/data/3.0/triggers/58528.../history/671e2...

[DELETE] /triggers/{:id}/history

This method is used to remove all history of alerts from a trigger. In case of successful removal service will return an HTTP-code 204 (Successful answer).

URL Example

http://api.openweathermap.org/data/3.0/triggers/5852816a9aaacb00153134a3/history

Weather Triggers Structure

Below is a complete description of the weather triggers and alerts data structures. All request and response parameters are also explained further in this section.

Struct Example 
              
{
   "__v":0,
   "_id":"585268b72516b90010058184",
   "alerts":{

   },
   "area":[
      {
         "type":"Point",
         "_id":"585268b72516b90010058185",
         "coordinates":[
            53,
            37
         ]
      }
   ],
   "conditions":[
      {
         "name":"temp",
         "expression":"$gt",
         "amount":299,
         "_id":"585268b72516b90010058186"
      }
   ],
   "time_period":{
      "end":{
         "expression":"after",
         "amount":432000000
      },
      "start":{
         "expression":"after",
         "amount":132000000
      }
   }
}
Parameters
_id Document id
owner User's id
time_period Time interval's scope used to do the matching between the weather data and the trigger conditions
conditions A set of conditions required for an alert creation
area A set of locations where the weather data will be collected and matched with a trigger conditions
alerts The named set of this trigger's current alerts

All fields contain a nested structure except the _id and the owner fields.

time_period

The structure of a time_period contains start and end fields. These fields also contain nested structures describing the beginning and the end of a time interval which is used to check the conditions.

The beginning and the end of a time interval represents a set of instructions for dynamic timestamp estimation. Timestamp is calculated considering the current time at the moment when conditions are being checked.

Parameters
amount Number of milliseconds
expression Specifies how to process value of the amount field.

The field expression has three admissible values:

  • exact - the field amount will be interpreted as a timestamp indicating an exact date/time
  • аfter - the field amount will be interpreted as a number of milliseconds which needs to be added to the current timestamp at the moment of validation to receive a chosen date/time.
  • before - the field amount will be interpreted as a number of milliseconds which needs to be subtracted from the current timestamp at the moment of validation to receive a chosen date/time.
Struct Example 
              
{
   "time_period":{
      "end":{
         "amount":432000000,
         "expression":"after"
      },
      "start":{
         "amount":132000000,
         "expression":"after"
      }
   }
}

conditions

The field conditions contains an array of objects describing the parameters that are used to do the comparison.

Parameters
name The name of the parameter to be compared with.

The following values are allowed: temp, pressure, humidity, wind_speed, wind_direction, clouds. Value of the name field specifies the corresponding parameter in a response from the Weather API which will be compared with.

expression The expression which will be used to compare.

Field expression indicates how exactly to perform comparison. The following values are available:

  • $gt - more than a value specified in amount.
  • $lt - less than a value specified in amount.
  • $gte - greater than or equals to a value specified in amount.
  • $lte - less than or equals to a value specified in amount.
  • $eq - equals to a value specified in amount.
  • $ne - not equals to a value specified in amount.
amount Numerical value to be compared with
Struct Example 
              
{
   "conditions":[
      {
         "name":"temp",
         "expression":"$gt",
         "amount":299,
         "_id":"57fcdd4d13b0c80024ac1faa"
      }
   ]
}

area

Field area is an array of objects, each of which could be interpreted as a point, a point set, polygon or set of polygons.

Parameters
type Object type
coordinates Set of coordinates

GeoJson is taken as a syntactic basis. In the type field the following values are allowed: Point, MultiPoint, Polygon, MultiPolygon.

Suchlike content is expected in the coordinates field, depending on the specified type:

type coordinates
Point [100.0, 0.0]
MultiPoint [ [100.0, 0.0], [101.0, 1.0] ]
Polygon (without hole) [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] ]
Polygon (with hole) [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],[ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ] ]
MultiPolygon [ [ [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0,3.0], [102.0, 2.0] ] ],[ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],[ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ] ] ]
Struct Example 
                  
    {
       "area":[
          {
             "type":"Point",
             "_id":"57fcdd4d13b0c80024ac1fa9",
             "coordinates":[
                53,
                37
             ]
          }
       ]
    }

alerts

The field alerts contains a set of key/value pairs. The MD5 line is an alert identifier and serves as a key. An identification key is composed of three parameters:

  • Timestamp, weather data was received for.
  • Type of weather API.
  • The coordinates of the query to weather API.
Parameters
conditions Current value and condition to fire on
last_update Time of the last check when this condition have been fired on
date Time of the measurement that matched a trigger's conditions
coordinates Coordinates, for which measurements were requested
Struct Example 
                  
{
   "alerts":{
      "671e2e711b86117906b4b81aa61c9bab":{
         "conditions":[
            {
               "current_value":{
                  "min":270.636,
                  "max":270.636
               },
               "condition":{
                  "name":"temp",
                  "expression":"$gt",
                  "amount":100,
                  "_id":"5832d39802ec0200200abe83"
               }
            }
         ],
         "last_update":1479902521846,
         "date":1480280400000,
         "coordinates":{
            "lon":53,
            "lat":37
         }
      }
   }
}

history_alerts

Data model in the history of alerts almost repeats the structure of alerts in a trigger object, but with two additional fields: owner and triggerId.

Parameters
_id Document id
owner user's id
triggerId id of a trigger
conditions Current value and condition to fire on
last_update Time of the last check when this condition have been fired on
date Time of the measurement that matched a trigger's conditions
coordinates Coordinates, for which measurements were requested