WeatherTrigger API

Request Components

The basic structure for all queries uses some or all of the following 'Components':

api/trigger/{Location}/{DataType} {Time} {Element} {Operator} {Value} {Unit}

Each of these query 'Components' will be available to the user to construct a logical query to return a response with a YES / NO answer. More info about response

Location

There are two different ways to specify the location:
Latitude/Longitude Co-ordinates or post code/zipcode.

Valid decimal geolocation coordinates with the following format: "latitude,longitude", with no more than 3 decimal places.

Example: For New York, was the average temperature yesterday greater than 10°C?
api/trigger/40.71,-74.00/past yesterday temperature.avg gt 10 C

A valid postcode with the following format: "country.postcode"
where country can be the available countries in our system.

Country Value Format (@ = Letter, # = Number)
United Kingdom 'uk' 'uk.postcode'
United States 'us' 'us.#####'
Argentina 'ar' 'ar.@####@@@'
Austria 'at' 'at.#####'
Australia 'au' 'au.#####'
Belgium 'be' 'be.####'
Brazil 'br' 'br.#####-###'
Canada 'ca' 'ca.@#@ #@#'
Denmark 'dk' 'dk.####'
Finland 'fi' 'fi.#####'
France 'fr' 'fr.#####'
Germany 'de' 'de.postcode'
Ireland 'ie' 'ie.@@@'
Italy 'it' 'it.#####'
Netherlands 'nl' 'nl.####'
Norway 'no' 'no.####'
Spain 'es' 'es.#####'
Sweden 'se' 'se.### ##'
Example: For Glasgow UK, was the average temperature yesterday greater than 10°C?
api/trigger/uk.G3 8ND/past yesterday temperature.avg gt 10 C
Example: For Miami USA, was the average temperature yesterday greater than 20°C?
api/trigger/us.33109/past yesterday temperature.avg gt 10

Please contact us if you would like postcodes to be made available for another country.

Data Type

There are 3 different Data Types you can query;

  • Past Weather
  • Current Weather
  • Forecast Weather

Please refer to the below tables for specific information on each Data Type;

You can query Past Weather data up to 7-days into the past. Past Weather queries require you define a ‘Time’. When you query Past Weather it will use the closest available data to your chosen location.

The Past Weather ‘Data Type’ is defined within the query using the text “pwx” or “past”

Request Structure:
api/trigger/{Location}/past {Element} {Time} {Operator} {Value}

Example: for London, was the temperature yesterday greater than 10 degrees?
api/trigger/51.50,-0.12/past yesterday temperature gt 10

You can query Current Weather data. There is no need to define a ‘Time’ when querying Current Weather. When you query Current Weather it will use the closest available data to your chosen location.

The Current Weather ‘Data Type’ is defined within the query using the text “cwx” or “current”

Request Structure
api/trigger/{Location}/Current {Element} {Operator} {Value}
Example: for London, is the current temperature greater than 10°C?
api/trigger/51.50,-0.12/current temperature gt 10

You can query Forecast Weather data up to 7-days into the future. Forecast Weather queries require you define a ‘Time’. When you query Forecast Weather it will use the closest available data to your chosen location.

The Forecast Weather ‘Data Type’ is defined within the query using the text “fwx” or “forecast”.

Request Structure
api/trigger/{Location}/forecast {Element} {TimePeriod} {Operator} {Value}
Example: for London, will the temperature tomorrow be greater than 10 degrees?
api/trigger/51.50,-0.12/forecast tomorrow temperature gt 10

Time

Time period is only required for "past" and "forecast" data types. Queries for Current weather data returns the closest live observations. The time period can be defined in 4 different ways:

For a specific interval between two points in time, must contain two dates in the following format. The hour part (hh) is optional.: "yyyy.mm.dd,yyyy.mm.dd" or "yyyy.mm.dd.hh,yyyy.mm.dd.hh"

Example: for Madrid, was the temperature between 25 January 2014 at 9h and 30 January 2014 at 18h less than 5°C?
api/trigger/40.38,-3.77/past 2014.01.25.9,2014.01.30.18 temperature lt 5 c

The day period can prefix a date with the following format: "day_period.yyyy.mm.dd"

The day period option helps run queries for specific periods in the day across multiple days. Day period prefix can be:

  • "day" - from 06:00 to 18:00
  • "night" - from 18:00 to 06:00 of the next day
  • "morning" - from 06:00 to 12:00
  • "afternoon" - from 12:00 to 18:00
  • "evening" - from 18:00 to 00:00
  • "overnight" - from 00:00 to 06:00
  • "am" - from 00:00 to 12:00
  • "pm" - from 12:00 to 00:00
Example: For Berlin, was the temperature in the morning of 25 January 2014 greater than 40°C?
api/trigger/52.48,13.41/past morning.2014.01.25 temperature gt 40 c

The day period can prefix a time frame between two dates, with the following format: "prefix.yyyy.mm.dd,yyyy.mm.dd"

Example: For Rome, was the wind speed in the afternoons between 20 and 25 January 2014 less than 30mph?
api/trigger/41.9,12.49/past afternoon.2014.01.20,2014.01.25 windspeed lt 30 mph

For a predefined time span use the following format: "predefined_timespan"
or you can postfix it with a day period: "predefined_timespan.day_period"

The predefined_timespan values can be:
  • "tomorrow" for "Forecast" data
  • "yesterday" for "Past" data
Example: For Beijing, was the temperature yesterday morning less than 10°C?
api/trigger/39.93,116.28/past yesterday.morning temperature lt 10 c

Element

The Precipitation Type element is defined within the query using the text “weather” or “wx”.

Operator
Equal - "eq"
Not Equal - "not"
Value

Any precipitation - "anyprecip"

Significant precipitation - "sigprecip"

Heavy precipitation - "heavyprecip"

Any rain - "anyrain" or "rain"

Significant rain - "sigrain"

Heavy rain - "heavyrain"

Any snow - "anysnow" or "snow"

Significant snow - "sigsnow"

Heavy snow - "heavysnow"


Example: For Sydney, will it rain tomorrow?
api/trigger/-33.84,151.19/forecast tomorrow weather eq anyrain

The Temperature element is defined within the query using the text “temperature” or “temp”. The Temperature element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Temperature element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Celsius "c" (default)

Fahrenheit "f"


Example 1: For Toronto, tomorrow will the temperature be greater than 20 degrees Celcius?
api/trigger/43.63,-79.4/forecast tomorrow temperature gt 20
Example 2: For Paris, tomorrow will the temperature be greater than 68 degrees Fahrenheit?
api/trigger/48.92,2.36/forecast tomorrow temperature gt 68 f

The Relative Humidity element is defined within the query using the text “humidity” or “hum”. The Relative Humidity element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Relative Humidity element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Percentage (default)


Example: For Moscow, tomorrow will the humidity be less than 10%?
api/trigger/55.75,37.63/forecast tomorrow humidity lt 10

The Wind Speed element is defined within the query using the text “windspeed” or “wspd”. The Wind Speed element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Wind Speed element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Meters per second "mps" (default)

Kilometers per hour "kmh"

Miles per hour "mph"

Knots "kn"


Example: For Rio de Janeiro, tomorrow will the wind speed be greater than 40 miles per hour?
api/trigger/-22.92,-43.17/forecast tomorrow windspeed gt 40 mph

The Wind Direction element is defined within the query using the text “winddirection” or “wdir”. The Wind Direction element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Wind Direction element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Between - "between"
Not Between - "notbetween"
Value
Degrees
Decimal value between 0 and 360 (inclusive). See notes
Compass points
Text value with the following format:
North "N"
North East "NE"
East "E"
South East "SE"
South "S"
South West "SW"
West "W"
North West "NW"
North "N"
Unit

degrees (default)

compass "com"

Notes on the use of degrees

Using 0 and 360 degrees

Values 0 and 360 in degrees are equivalent and queries can accept either value. Therefore 0,90 degrees is equivalent to 360,90 degrees.

Between compass points

Between x,y - "x" is the start value, and "y" the finish value in a clockwise direction. Both values are also included.
Therefore between 45 and 90 degrees (45,90) would cover 45,46,47 ... 88,89,90 degrees.
Whereas between 90 and 45 degrees (90,45) would cover 90,91,92 ... 43,44,45.

The same principal is applied to compass values.
For example SE,NE would cover SE,S,SW,W,NW,N,NE compass points.


Example 1: For London, tomorrow will the wind direction be between 90 and 180?
api/trigger/51.50,-0.12/forecast tomorrow winddirection between 90,180
Example 2: For London, tomorrow will the wind direction be between south and south east?
api/trigger/51.50,-0.12/forecast tomorrow winddirection between S,SE com

The Cloud Cover element is defined within the query using the text “Cloud” or “cld”. The Cloud Cover element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Cloud Cover element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Percentage (default)


Example: For London, tomorrow will the cloud cover be greater than 90%?
api/trigger/51.50,-0.12/forecast tomorrow cloud gt 90

The Visibility element is defined within the query using the text “visibility” or “vis”. The Visibility element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Visibility element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Kilometers "km" (default)

Miles "mi" (default)


Example 1: For London, tomorrow will the visibility be less than 2 kilometers?
api/trigger/51.50,-0.12/forecast tomorrow visibility lt 2
Example 2: For London, tomorrow will the visibility be greater than 5 miles?
api/trigger/51.50,-0.12/forecast tomorrow visibility gt 5 mi

The Air Pressure element is defined within the query using the text “pressure” or “pres”. The Air Pressure element can be used for the following ‘Data Types’;

  • Past
  • Current
  • Forecast

When using the Air Pressure element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Millibars "mb" (default)

Inches "in"


Example: For London, tomorrow will the pressure be greater than 15 millibars?
api/trigger/51.50,-0.12/forecast tomorrow pressure gt 15

The Precipitation Amount element is defined within the query using the text “precipitation” or “preciptl”. The Precipitation Amount element can be used for the following ‘Data Types’;

  • Forecast

When using the Precipitation Amount element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Millimeters "m" (default)

Inches "in"


Example: For London, tomorrow will the precipitation be greater than 50 millimeters?
api/trigger/51.50,-0.12/forecast tomorrow precipitation gt 50

The Rainfall Amount element is defined within the query using the text “raintl”. The Rainfall Amount element can be used for the following ‘Data Types’;

  • Forecast

When using the Rainfall Amount element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Millimeters "m" (default)

Inches "in"


Example: For London, tomorrow will the rainfall be less than 50 millimeters?
api/trigger/51.50,-0.12/forecast tomorrow rain lt 50

The Snowfall Amount element is defined within the query using the text “snowtl”. The Snowfall Amount element can be used for the following ‘Data Types’;

  • Forecast

When using the Snowfall Amount element within the query the following ‘Operators’, ‘Values’ and ‘Units’ can be applied;

Operator
Greater Than - "gt"
Less Than - "lt"
Greater Than or equal - "gteq"
Less Than or equal - "lteq"
Value

decimal value

Unit

Centimeters "cm" (default)

Inches "in"


Example: For London, tomorrow will the snowfall be less than 50 centimeters?
api/trigger/51.50,-0.12/forecast tomorrow snow lt 50

Element Functions

The ‘average’ function is defined by adding the text ‘.avg’ to the end of an element within a query. The ‘average’ function will return a response based on the ‘Element average’ for the defined time period.

The ‘average’ function can be added into queries using ‘Past’ and ‘Forecast’ data.

The ‘average’ function cannot be added into queries using ‘Current’ data.

The ‘average’ function can be added to the following elements;

Past
Temperature
Humidity
Wind Speed
Cloud Cover
Visibility
Air Pressure
Forecast
Temperature
Humidity
Wind Speed
Cloud Cover
Visibility
Air Pressure
Example: for London, was the average temperature yesterday greater than 20 degrees Celcius?
api/trigger/51.50,-0.12/past yesterday temperature.avg gt 20