Insights API

An insight can be defined by either:

Starting from scratch by configuring it with a combination of parameters, operators, and constants that determine if a matching Event is forecasted to occur
Starting from any of our rich collection of Templates, based on real industry use-cases
Subscribing to an Insight Category (that encompasses various similar events reported by our sources)

Operators

The simplest form of a condition consists of an OPERATOR, a PARAMETER, and a CONST. When the engine runs, the operator is used to compare the parameter against the constant. If the result is truthy, the condition passes.

Each operator node has three properties:

type: a string that sets the type of the node - always OPERATOR
content: an object that contains the definition of the operator - for example operator: AND
children: an array with the collection of chained conditions

{
    "type": "OPERATOR",
    "content": {
        "operator": "AND"
    },
    "children": [{
            "type": "OPERATOR",
            "content": {
                "operator": "EQUAL"
            },
            "children": [{
                    "type": "PARAMETER",
                    "content": {
                        "parameter": "precipitationType"
                    }
                },
                {
                    "type": "CONST",
                    "content": {
                        "const": 1
                    }
                }
            ]
        },
        {
            "type": "OPERATOR",
            "content": {
                "operator": "GREATER"
            },
            "children": [{
                    "type": "PARAMETER",
                    "content": {
                        "parameter": "precipitationIntensity"
                    }
                },
                {
                    "type": "CONST",
                    "content": {
                        "const": 0.5
                    }
                }
            ]
        }

    ]
}

Logical Operators:
These operators must have at least two child nodes, of type OPERATOR. Notice that AND and OR can be nested within one another to produce complex boolean expressions. These operators must have at least two children.

Operator	Description
`AND`	specifies that all child conditions contained within must be truthy for the condition to be considered a success
`OR`	requires one child condition to be truthy for the condition to succeed

Comparison Operators:
These operators must have one child node of type PARAMETER and another of type CONST in this order, such that their value types match. For example precipitationType can only have string values and therefor the constant it is compared against must be a string.

Operator	Description
`GREATER`	`PARAMETER` must be greater than `CONST` to be considered truthy
`GREATER_EQUAL`	`PARAMETER` must be greater than or equal to `CONST` to be considered truthy
`LESS`	`PARAMETER` must be less than `CONST` to be considered truthy
`LESS_EQUAL`	`PARAMETER` must be less than or equal to `CONST` to be considered truthy
`EQUAL`	`PARAMETER` must equal `CONST` to be considered truthy

Time Operator:
These operators must have two child nodes, either PARAMETER or CONST types, such that they describe a time period within a single day (00:00 until 23:59) in a monitored Location's timezone. Using sunriseTime and sunsetTime parameter that match the Location's specific times.

Operator	Description
`TIME_IN_DAY`	must occur in the time in day between the first and second child to be considered truthy, whereas a child is defined by a `PARAMETER` (like `sunsetTime` or `sunriseTime`) or `CONST` like (`18:00`)

Parameters

For non-logical operators, PARAMETER children represent the conditions of observed/forecasted values at the monitored location. Read more about facts in the next section.

In case a field name suffix is not defined, Polygons will use the default type (see Data Layers). In case an Insight has a Min/Max/Average suffix and is checked for a Point location, the suffix will be omitted.

Each parameter node has two properties:

type: a string that sets the type of the node - always PARAMETER
content: an object that contains the definition of the data field name for the parameter to check against a constant (or operator such as TIME_IN_DAY) - such as precipitationType, precipitationIntensity or sunsetTime

Constants

For non-logical operators, CONST children represent constant values to check the other child value against (can be parameters, constants, or other operators).

Each const node has two properties:

type: a string that sets the type of the node - always CONST
content: an object that contains the value to check against the parameter (or operator such as TIME_IN_DAY) - for example, rain, 15, or 18:00 and must match the same type (like string, float etc).