ReferenceRecipesFAQsHelp CenterBlogAPI Status
Reference
Get Your Free API Key

Custom Events API

A Custom Vector Events feed quickly aggregates weather events derived from your custom insights—configurable weather thresholds and protocols that you define, or select from a library of industry-popular protocols. With feed settings like refresh rate, resolution, and timeframe, you can tailor how these events are generated to reflect your organization’s unique needs. Once configured, these events can be integrated into any GIS or map-based solution, enabling automated workflows, streamlined decision-making, and provide deeper visibility into weather impacts across your operations.

1. Feed Creation

A feed is composed of several monitors grouped together to create a unified feed of different weather events. The monitors can use any insight - from Tomorrow.io's library or a custom insight. The feed is then consumed using the Custom Vector Events API. A Custom Vector Events feed is configured by Tomorrow.io according to customer-selected settings (refresh rate, timestep, time frame, resolution, batch window, area). Once configured, the feed generates a unified set of weather events that can be retrieved via the public endpoints detailed below.

We provide a sample feed named "sample" so you can quickly explore how the data is structured and how queries can be made.

2. Events API

Response Formats

The endpoint supports two response formats: .json and .geojson. Each format provides details about weather events, but the structure and purpose of the responses differ to suit various use cases. Below is a summary of both formats:

JSON Format

The .json response format is a structured, tabular representation of weather events. It is designed for scenarios where detailed event metadata and precise attributes are required.
Structure: The response includes an array of event objects. Each object contains attributes such as event ID, time range, affected locations, and metadata.
Use Case: Ideal for applications that need detailed event data for programmatic analysis or integration into business workflows.

GeoJSON Format

The .geojson response format follows the GeoJSON specification and is tailored for geospatial applications. It represents events as geographic features, making it compatible with mapping tools and GIS platforms.
Structure: The response is a FeatureCollection containing Feature objects. Each feature has a geometry field (defining the affected area as a polygon) and a properties field (containing metadata about the event).
Use Case: Best suited for mapping, visualization, or geospatial analysis of weather events.

Sample Response:

{
  "events": [
    {
      "id": 0,
      "object_key": "0738ee6491d6a1de7e5c0c6c592ae9r0",
      "start": "2025-01-06T00:00:00Z",
      "end": "2025-01-07T00:00:00Z",
      "locations": [
        {
          "geojsonGeometry": {
            "coordinates": [
              [
                [-63.80859374999999, 52.277379792414685],
                [-63.6328125, 52.277379792414685],
                [-63.6328125, 52.38482863733332],
                [-63.80859374999999, 52.38482863733332],
                [-63.80859374999999, 52.277379792414685]
              ]
            ],
            "type": "Polygon"
          }
        }
      ],
      "attributes": {
        "accountId": "7436tf07f72afr651e2480fg5tg9f",
        "insightId": "c216753-3fbc-4454-9c48-3dec743b4210",
        "insightName": "6 Hour Snow Accumulation",
        "locationId": "us_continental",
        "severity": "severe"
      }
    }
  ]
}


{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-114.60937499999999, 45.834886584131745],
            [-114.43359375, 45.834886584131745],
            [-114.43359375, 45.957348270500816],
            [-114.60937499999999, 45.957348270500816],
            [-114.60937499999999, 45.834886584131745]
          ]
        ]
      },
      "properties": {
        "start": "2025-01-07T00:00:00Z",
        "end": "2025-01-07T01:00:00Z",
        "accountId": "6630ee07f72add651c560f3b",
        "insightId": "211e7292-4099-48ac-8371-c2fbf1bfc54e",
        "insightName": "6 Hour Snow Accumulation",
        "locationId": "us_continental",
        "severity": "severe"
	 "insightDescription":"Heavy snow accumulation of more than 6 inches expected"
      }
    }
  ]
}

Event Object Attributes/Properties

The Event Object represents a weather-related occurrence, providing details about its timing, location, and metadata.

Attributes/Properties:

  • start (string, ISO 8601): The UTC timestamp indicating when the event starts, formatted as YYYY-MM-DDTHH:mm:ssZ.
  • end (string, ISO 8601): The UTC timestamp indicating when the event ends, formatted as YYYY-MM-DDTHH:mm:ssZ.
  • attributes (object): A collection of metadata related to the event:
    • insightId (string): The unique identifier of the insight that triggered the event.
    • insightName (string): The name of the associated insight created in Tomorrow.io's platform or via API.
    • locationId (string): An identifier for the general location category. You will recieve this from Tomorrow.io based on the area your feed is configured to cover.
    • severity (string): The severity level of the event as defined in the insight.
    • insightDescription (string): the description of the insight created in Tomorrow.io's platform or via API.

Endpoint Usage Example

Fetch all events from a feed

Filter events by time

  • To filter events by time, provide a timeRange field in the body of the request.
  • Times should follow the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
  • Fetch events up to a specific time:
{ 
   "timeRange": {  
       "to": "2025-01-02T23:59:00Z"  
   }  
}

Fetch events starting from a specific time:

{  
   "timeRange": {  
       "from": "2025-01-02T00:01:00Z"  
   }  
}

Fetch events for a specific time range:

{  
   "timeRange": {  
       "from": "2025-01-02T00:01:00Z",  
       "to": "2025-01-02T23:59:00Z"  
   }  
}

Filter events by area

  • To filter events by a specific area, include a geofence field in the body of the request. This field should define the desired geometry using GeoJSON format.
{  
   "geofence": {  
       "geojsonGeometry": {  
           "type": "Polygon",
           "coordinates": [  
                [  
               	[-104.70273345194833, 43.89808150147567],  
               	[-104.70273345194833, 40.51070838161783],  
               	[ -95.90647971392198, 40.51070838161783],  
               	[ -95.90647971392198, 43.89808150147567],  
               	[-104.70273345194833, 43.89808150147567]  
               ]  
           ]  
       }  
   }  
}

Filter events by attributes
To filter events by specific attributes, include an attributes field in the body of the request. This field should be a key-value map where each key represents an attribute name, and the corresponding value specifies the desired value for filtering. For example, to fetch all events associated with a specific insight, provide the relevant attributes.insightId.

{  
   "attributes": {  
       "insightId": "d3dabf22-9877-4688-b2b9-e71eaf521838"  
   }  
}