Tomorrow.io Logo

Insights API

The Insights API allows you to create and manage weather-based insights that can be used for automated monitoring and alerting. Insights are defined by custom conditions using weather parameters, severity levels, and descriptive tags.

Key Features: Custom weather condition logic • Severity level classification • Tag-based organization • Integration with monitoring and alerting systems

Information

Important: Insight endpoint units are in Metric. Deleting an insight will result in deleting any linked alerts, and removing it from linked dashboards.

Conditions Structure

Basic Condition Structure

Conditions are defined using a tree structure with operators and parameters. Each condition has a type, content, and optional children array.

Basic Condition ExampleJSON
{
  "type": "OPERATOR",
  "content": {
    "operator": "GREATER"
  },
  "children": [
    {
      "type": "PARAMETER",
      "content": {
        "parameter": "windSpeed"
      }
    },
    {
      "type": "CONST",
      "content": {
        "const": 25
      }
    }
  ]
}

Supported Operators

Comparison Operators

  • • GREATER - Greater than (>)
  • • GREATER_EQUAL - Greater than or equal (>=)
  • • LESS - Less than (<)
  • • LESS_EQUAL - Less than or equal (<=)
  • • EQUAL - Equal to (=)

Logical Operators

  • • AND - Logical AND
  • • OR - Logical OR
  • • DURATION - Duration-based conditions

Severity Levels

Available Severity Levels

  • • unknown - Severity not determined
  • • minor - Low impact conditions
  • • moderate - Medium impact conditions
  • • severe - High impact conditions
  • • extreme - Critical impact conditions

Usage Guidelines

The severity level indicates the intensity of impact when conditions occur. Use appropriate severity levels to prioritize alerts and responses.

List Insights

List Insights

https://api.tomorrow.io/v4/insights

Request Parameters

ParameterTypeRequiredDescriptionExample
apikeyStringRequiredYour Tomorrow.io API key for authenticationYOUR_API_KEY

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/insights?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "insights": [
      {
        "id": "003cccdd-d088-4051-b432-6244e094c6b1",
        "type": "standard",
        "conditions": {
          "type": "OPERATOR",
          "content": {
            "operator": "LESS"
          },
          "children": [
            {
              "type": "PARAMETER",
              "content": {
                "parameter": "temperature"
              }
            },
            {
              "type": "CONST",
              "content": {
                "const": 1
              }
            }
          ]
        },
        "name": "Implement Extreme Cold Protocol: Low Temps",
        "description": "Salt surfaces and avoid any unnecessary work outdoors. Brief employees for general weather safety operations (frost bite, hypothermia, slipping on ice, etc.).",
        "severity": "minor",
        "tags": [
          "Maritime Operations 2025-05-28 21:41"
        ],
        "createdAt": "2025-05-28T21:41:19.569Z",
        "updatedAt": "2025-05-28T21:41:19.569Z",
        "isAccountResource": true
      },
      {
        "id": "02008acb-d36a-47f9-b43e-19f107021219",
        "type": "standard",
        "conditions": {
          "type": "OPERATOR",
          "content": {
            "operator": "DURATION"
          },
          "children": [
            {
              "type": "CONST",
              "content": {
                "const": 180
              }
            },
            {
              "type": "OPERATOR",
              "content": {
                "operator": "GREATER_EQUAL"
              },
              "children": [
                {
                  "type": "PARAMETER",
                  "content": {
                    "parameter": "precipitationIntensity"
                  }
                },
                {
                  "type": "CONST",
                  "content": {
                    "const": 7.5
                  }
                }
              ]
            }
          ]
        },
        "name": "Prepare Elevated Shelter: Heavy Rain",
        "description": "Risk Knowledge: Waters may damage lower levels of buildings and homes. People need elevated shelter. Communicate Risk: Local officials and residents\nResponse Capability: Ensure there are enclosed shelters above ground that can house people who need shelter when water levels rise.",
        "severity": "extreme",
        "tags": [
          "Early Warning System: Floods  2025-06-02 12:29"
        ],
        "createdAt": "2025-06-02T12:29:05.353Z",
        "updatedAt": "2025-06-02T12:29:05.353Z",
        "isAccountResource": true
      },
      {
        "id": "02f70a75-317c-439a-83ad-6bba0685afe9",
        "type": "standard",
        "conditions": {
          "type": "OPERATOR",
          "content": {
            "operator": "LESS"
          },
          "children": [
            {
              "type": "PARAMETER",
              "content": {
                "parameter": "visibility"
              }
            },
            {
              "type": "CONST",
              "content": {
                "const": 1
              }
            }
          ]
        },
        "name": "Implement Fog Protocol: Poor Visibility",
        "description": "Slow down and consider dropping anchor if necessary. Listen to audio signals from the surrounding and blow your horn as needed. Use radar and electronics. Notify crews.",
        "severity": "extreme",
        "tags": [
          "Maritime Operations 2025-05-28 21:41"
        ],
        "createdAt": "2025-05-28T21:41:19.587Z",
        "updatedAt": "2025-05-28T21:41:19.587Z",
        "isAccountResource": true
      }
    ]
  },
  "meta": {
    "totalItems": 119
  },
  "links": {
    "self": "/v4/insights?limit=10&offset=0",
    "next": "/v4/insights?limit=10&offset=10"
  }
}

Create an Insight

Create Insight

https://api.tomorrow.io/v4/insights

Request Parameters

ParameterTypeRequiredDescriptionExample
nameStringRequiredThe name of the insight used when setting alert notificationsHigh Wind Alert
rulesStringOptionalThe rules for which the linked locations will be checked. Either rules or conditions is required (e.g., windSpeed > 30)windSpeed > 30
conditionsJSONOptionalThe conditions for which the linked locations will be checked. Either rules or conditions is required{"type": "OPERATOR", "content": {"operator": "GREATER"}, "children": [...]}
tagsArray<String>OptionalAny descriptive tags to be used to filter insights["weather", "safety"]
severityStringOptionalThe code denoting the intensity of impact when conditions occur (extreme, severe, moderate, minor, unknown)moderate
descriptionStringOptionalThe description detailing this insight use-caseMonitor wind conditions and implement safety protocols when wind speeds exceed threshold

Request Example

cURL RequestBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/insights?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "High Wind Alert",
    "rules": "windSpeed > 25",
    "tags": ["weather", "safety", "wind"],
    "severity": "moderate",
    "description": "Monitor wind conditions and implement safety protocols when wind speeds exceed 25 m/s."
  }'

Response Example

201 Success ResponseJSON
{
  "data": {
    "insight": {
      "id": "51b1c71b-3ba7-4b6d-b5ff-702c35937ea4",
      "type": "standard",
      "conditions": {
        "type": "OPERATOR",
        "content": {
          "operator": "GREATER"
        },
        "children": [
          {
            "type": "PARAMETER",
            "content": {
              "parameter": "windSpeed"
            }
          },
          {
            "type": "CONST",
            "content": {
              "const": 25
            }
          }
        ]
      },
      "name": "High Wind Alert",
      "description": "Monitor wind conditions and implement safety protocols when wind speeds exceed 25 m/s. Secure loose objects and consider postponing outdoor activities.",
      "severity": "moderate",
      "tags": [
        "weather",
        "safety",
        "wind"
      ],
      "createdAt": "2025-07-07T04:28:30.133Z",
      "updatedAt": "2025-07-07T04:28:30.133Z",
      "isAccountResource": true
    }
  }
}

Retrieve an Insight

Retrieve Insight

https://api.tomorrow.io/v4/insights/{insightId}

Request Parameters

ParameterTypeRequiredDescriptionExample
insightIdStringRequiredID of a pre-defined insightinsight_id_123
apikeyStringRequiredYour Tomorrow.io API key for authenticationYOUR_API_KEY

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/insights/insight_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "insight": {
      "id": "51b1c71b-3ba7-4b6d-b5ff-702c35937ea4",
      "type": "standard",
      "conditions": {
        "type": "OPERATOR",
        "content": {
          "operator": "GREATER"
        },
        "children": [
          {
            "type": "PARAMETER",
            "content": {
              "parameter": "windSpeed"
            }
          },
          {
            "type": "CONST",
            "content": {
              "const": 25
            }
          }
        ]
      },
      "name": "High Wind Alert",
      "description": "Monitor wind conditions and implement safety protocols when wind speeds exceed 25 m/s. Secure loose objects and consider postponing outdoor activities.",
      "severity": "moderate",
      "tags": [
        "weather",
        "safety",
        "wind"
      ],
      "createdAt": "2025-07-07T04:28:30.133Z",
      "updatedAt": "2025-07-07T04:28:30.133Z",
      "isAccountResource": true
    }
  }
}

Update an Insight

Update Insight

https://api.tomorrow.io/v4/insights/{insightId}

Request Parameters

ParameterTypeRequiredDescriptionExample
insightIdStringRequiredID of a pre-defined insightinsight_id_123
nameStringOptionalThe name of the insight used when triggering alert notificationsUpdated High Wind Alert
rulesStringOptionalThe rules for which the linked locations will be checked. i.e (windSpeed > 30)windSpeed > 35
conditionsJSONOptionalThe conditions for which the linked locations will be checked{"type": "OPERATOR", "content": {"operator": "GREATER"}, "children": [...]}
tagsArray<String>OptionalAny descriptive tags to be used to filter insights["weather", "safety", "updated"]
severityStringOptionalThe code denoting the intensity of impact when conditions occursevere
descriptionStringOptionalThe description detailing this insight use-caseUpdated description for the insight

Request Example

cURL RequestBASH
curl --request PUT \
  --url 'https://api.tomorrow.io/v4/insights/insight_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated High Wind Alert",
    "severity": "severe",
    "description": "Updated description for enhanced wind monitoring"
  }'

Response Example

200 Success ResponseJSON
{
  "data": {
    "insight": {
      "id": "insight_id_123",
      "type": "standard",
      "conditions": {
        "type": "OPERATOR",
        "content": {
          "operator": "GREATER"
        },
        "children": [
          {
            "type": "PARAMETER",
            "content": {
              "parameter": "windSpeed"
            }
          },
          {
            "type": "CONST",
            "content": {
              "const": 25
            }
          }
        ]
      },
      "name": "Updated High Wind Alert",
      "description": "Updated description for enhanced wind monitoring",
      "severity": "severe",
      "tags": [],
      "createdAt": "2025-07-07T04:28:30.133Z",
      "updatedAt": "2025-07-07T04:28:49.174Z",
      "isAccountResource": true
    }
  }
}

Delete an Insight

Delete Insight

https://api.tomorrow.io/v4/insights/{insightId}

Warning

Deleting an insight will result in deleting any linked alerts, and removing it from linked dashboards.

Request Parameters

ParameterTypeRequiredDescriptionExample
insightIdStringRequiredID of a pre-defined insightinsight_id_123
apikeyStringRequiredYour Tomorrow.io API key for authenticationYOUR_API_KEY

Request Example

cURL RequestBASH
curl --request DELETE \
  --url 'https://api.tomorrow.io/v4/insights/insight_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

204 Success ResponseJSON
{
  "message": "Insight deleted successfully"
}

Add Insight Tags

Add Insight Tags

https://api.tomorrow.io/v4/insights/tags/add

Request Parameters

ParameterTypeRequiredDescriptionExample
insightsArray<String>RequiredList of insight IDs to add tags to["insight_id_1", "insight_id_2"]
tagsArray<String>RequiredList of tags to be added to insights["urgent", "monitoring"]

Request Example

cURL RequestBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/insights/tags/add?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "insights": ["insight_id_1", "insight_id_2"],
    "tags": ["urgent", "monitoring"]
  }'

Response Example

204 Success ResponseJSON
{
  "message": "Tags added successfully"
}

Remove Insight Tags

Remove Insight Tags

https://api.tomorrow.io/v4/insights/tags/remove

Request Parameters

ParameterTypeRequiredDescriptionExample
insightsArray<String>RequiredList of insight IDs to remove tags from["insight_id_1", "insight_id_2"]
tagsArray<String>RequiredList of tags to be removed from insights["urgent", "monitoring"]

Request Example

cURL RequestBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/insights/tags/remove?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "insights": ["insight_id_1", "insight_id_2"],
    "tags": ["urgent", "monitoring"]
  }'

Response Example

204 Success ResponseJSON
{
  "message": "Tags removed successfully"
}

Error Responses

400 Bad Request

Invalid Request FormatJSON
{
  "code": 400,
  "type": "Bad Request",
  "message": "Invalid request format or missing required parameters"
}

401 Unauthorized

Invalid API KeyJSON
{
  "code": 401,
  "type": "Unauthorized",
  "message": "Invalid API key or insufficient permissions"
}

404 Not Found

Insight Not FoundJSON
{
  "code": 404,
  "type": "Not Found",
  "message": "Insight not found"
}