Tomorrow.io LLM-Friendly Weather API Documentation

Overview

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.

Key Features

• Custom insights integration: Events derived from your custom weather thresholds and protocols
• Dual format support: JSON for tabular data, GeoJSON for geospatial applications
• Advanced filtering: Filter by time range, geographic area, and event attributes
• GIS compatibility: GeoJSON format works with mapping tools and GIS platforms
• Configurable feeds: Tailored refresh rates, resolution, and timeframes
• Sample feed available: Explore data structure with the "sample" feed

Feed Creation Process:

• Monitor grouping: Multiple monitors grouped together to create unified feeds
• Insight integration: Use insights from Tomorrow.io's library or custom insights
• Custom configuration: Configured by Tomorrow.io based on your selected settings
• Automated workflows: Enable streamlined decision-making and operational visibility

Response Formats

The Custom Events API supports two response formats to suit different use cases and integration requirements.

JSON Format

Structured, tabular representation of weather events designed for detailed event metadata and precise attributes.

Best for:

• Programmatic analysis
• Business workflow integration
• Detailed event metadata processing

GeoJSON Format

Geographic features following GeoJSON specification, tailored for geospatial applications and mapping tools.

Best for:

• Mapping and visualization
• GIS platform integration
• Geospatial analysis

Authentication

All Custom Events API endpoints require authentication using your Tomorrow.io API key. Include your API key as a query parameter in all requests.

Authentication Method: API Key (query parameter)
Parameter Name: apikey
Example: ?apikey=YOUR_API_KEY

Retrieve Custom Events

https://api.tomorrow.io/v4/events-custom/{feedName}.{format}?apikey={apikey}

Path Parameters

Parameter	Type	Required	Description	Example
`feedName`	string	Required	The name of your custom feed. Use "sample" to explore the demo feed.	`sample`
`format`	string	Required	Response format: "json" for tabular data or "geojson" for geospatial applications	`geojson`

Query Parameters

Parameter	Type	Required	Description	Example
`apikey`	string	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Body (Optional Filters)

Include filter parameters in the request body to narrow down results:

Parameter	Type	Required	Description	Example
`timeRange`	object	Optional	Filter events by time range using ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)	`{"from": "2025-01-02T00:01:00Z", "to": "2025-01-02T23:59:00Z"}`
`geofence`	object	Optional	Filter events by geographic area using GeoJSON geometry	`{"geojsonGeometry": {"type": "Polygon", "coordinates": [...]}}`
`attributes`	object	Optional	Filter events by specific attributes (key-value pairs)	`{"insightId": "d3dabf22-9877-4688-b2b9-e71eaf521838"}`

Example Request URLs

JSON Format:

curl -X POST "https://api.tomorrow.io/v4/events-custom/sample.json?apikey=YOUR_API_KEY"

GeoJSON Format:

curl -X POST "https://api.tomorrow.io/v4/events-custom/sample.geojson?apikey=YOUR_API_KEY"

Response Example (JSON Format)

{
  "events": [
    {
      "id": 0,
      "object_key": "805069d658f46a361f60170d3774eaa3",
      "name": "",
      "start": "2025-07-07T00:00:00Z",
      "end": "2025-07-07T01:00:00Z",
      "locations": [
        {
          "geojsonGeometry": {
            "coordinates": [
              [
                [
                  -111.97265625000001,
                  34.60647278491063
                ],
                [
                  -111.79687499999999,
                  34.60647278491063
                ],
                [
                  -111.79687499999999,
                  34.750873813803885
                ],
                [
                  -111.97265625000001,
                  34.750873813803885
                ],
                [
                  -111.97265625000001,
                  34.60647278491063
                ]
              ]
            ],
            "type": "Polygon"
          }
        }
      ],
      "attributes": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "insightDescription": "Temperatures above 100°F expected in this area. \n\nReduced employee productivity, increased risk of equipment failure or damage, increased demand for energy to maintain indoor climate control.",
        "insightId": "e735d6c1-883c-4ad7-b9d1-0ffdb897b43e",
        "insightName": "Extreme Heat",
        "locationId": "us_continental",
        "severity": "moderate",
        "tags": []
      },
      "accountId": ""
    },
    {
      "id": 0,
      "object_key": "9accf610116c5cbf7a632c19a9e4e448",
      "name": "",
      "start": "2025-07-07T11:00:00Z",
      "end": "2025-07-07T12:00:00Z",
      "locations": [
        {
          "geojsonGeometry": {
            "coordinates": [
              [
                [
                  -101.25,
                  35.46905518000711
                ],
                [
                  -101.07421875,
                  35.46905518000711
                ],
                [
                  -101.07421875,
                  35.754535032803425
                ],
                [
                  -101.25,
                  35.754535032803425
                ],
                [
                  -101.25,
                  35.46905518000711
                ]
              ]
            ],
            "type": "Polygon"
          }
        }
      ],
      "attributes": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "insightDescription": "Heavy rainfall expected in this area: rate of > 2 inches per hour\n\nPotential floods, landslides, road closures, transportation disruptions, power outages due to fallen trees or damaged power lines, property damage.",
        "insightId": "1e17fc87-cc70-493c-9afe-19e9700ce07c",
        "insightName": "Heavy Rain",
        "locationId": "us_continental",
        "severity": "severe",
        "tags": []
      },
      "accountId": ""
    },
    {
      "id": 0,
      "object_key": "64338e612eaace2162db49965cddbdda",
      "name": "",
      "start": "2025-07-07T07:00:00Z",
      "end": "2025-07-07T08:00:00Z",
      "locations": [
        {
          "geojsonGeometry": {
            "coordinates": [
              [
                [
                  -101.25,
                  37.72389488698566
                ],
                [
                  -101.07421875,
                  37.72389488698566
                ],
                [
                  -101.07421875,
                  38.00105449220598
                ],
                [
                  -101.25,
                  38.00105449220598
                ],
                [
                  -101.25,
                  37.72389488698566
                ]
              ]
            ],
            "type": "Polygon"
          }
        }
      ],
      "attributes": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "insightDescription": "Winds above 40 MPH or gusts greater than 55 MPH Expected in this area. Extreme danger for large trucks. Secure all equipment.",
        "insightId": "e41b147d-7158-4925-9ec8-fce6acddfc48",
        "insightName": "Strong Winds",
        "locationId": "us_continental",
        "severity": "severe",
        "tags": []
      },
      "accountId": ""
    }
  ],
  "routes": [],
  "assets": []
}

Response Example (GeoJSON Format)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.51953125000001,
              40.314207342550425
            ],
            [
              -122.34374999999999,
              40.314207342550425
            ],
            [
              -122.34374999999999,
              40.447880639867456
            ],
            [
              -122.16796875,
              40.447880639867456
            ],
            [
              -122.16796875,
              40.714424857817406
            ],
            [
              -122.34374999999999,
              40.714424857817406
            ],
            [
              -122.34374999999999,
              40.581286538362036
            ],
            [
              -122.51953125000001,
              40.581286538362036
            ],
            [
              -122.51953125000001,
              40.314207342550425
            ]
          ]
        ]
      },
      "properties": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "endTime": "2025-07-07T02:00:00Z",
        "insightDescription": "Temperatures above 100°F expected in this area. \n\nReduced employee productivity, increased risk of equipment failure or damage, increased demand for energy to maintain indoor climate control.",
        "insightId": "e735d6c1-883c-4ad7-b9d1-0ffdb897b43e",
        "insightName": "Extreme Heat",
        "locationId": "us_continental",
        "severity": "moderate",
        "startTime": "2025-07-07T00:00:00Z",
        "tags": []
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -108.984375,
              27.23089147563036
            ],
            [
              -108.80859375,
              27.23089147563036
            ],
            [
              -108.80859375,
              27.38703356673941
            ],
            [
              -108.984375,
              27.38703356673941
            ],
            [
              -108.984375,
              27.23089147563036
            ]
          ]
        ]
      },
      "properties": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "endTime": "2025-07-07T05:00:00Z",
        "insightDescription": "Heavy rainfall expected in this area: rate of > 2 inches per hour\n\nPotential floods, landslides, road closures, transportation disruptions, power outages due to fallen trees or damaged power lines, property damage.",
        "insightId": "1e17fc87-cc70-493c-9afe-19e9700ce07c",
        "insightName": "Heavy Rain",
        "locationId": "us_continental",
        "severity": "severe",
        "startTime": "2025-07-07T04:00:00Z",
        "tags": []
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -102.48046874999999,
              38.962811565424225
            ],
            [
              -102.12890625,
              38.962811565424225
            ],
            [
              -102.12890625,
              39.099147556361956
            ],
            [
              -102.3046875,
              39.099147556361956
            ],
            [
              -102.3046875,
              39.23521829761008
            ],
            [
              -102.48046874999999,
              39.23521829761008
            ],
            [
              -102.48046874999999,
              38.962811565424225
            ]
          ]
        ]
      },
      "properties": {
        "accountId": "63fe3264e5b2f04fc03edb7f",
        "endTime": "2025-07-07T04:00:00Z",
        "insightDescription": "Winds above 40 MPH or gusts greater than 55 MPH Expected in this area. Extreme danger for large trucks. Secure all equipment.",
        "insightId": "e41b147d-7158-4925-9ec8-fce6acddfc48",
        "insightName": "Strong Winds",
        "locationId": "us_continental",
        "severity": "severe",
        "startTime": "2025-07-07T03:00:00Z",
        "tags": []
      }
    }
  ]
}

Filtering Examples

Use POST request body parameters to filter events by time, location, and attributes.

Filter by Time Range

Filter events within a specific time period:

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

Filter by Geographic Area

Filter events within a specific geographic boundary:

{
  "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 by Attributes

Filter events by specific insight or other attributes:

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

Event Object Structure

Each event object contains detailed information about weather-related occurrences, including timing, location, and metadata.

Event Attributes/Properties

Parameter	Type	Required	Description	Example
`start`	string	Required	UTC timestamp when the event starts (ISO 8601 format)	`2025-01-06T00:00:00Z`
`end`	string	Required	UTC timestamp when the event ends (ISO 8601 format)	`2025-01-07T00:00:00Z`
`insightId`	string	Required	Unique identifier of the insight that triggered the event	`c216753-3fbc-4454-9c48-3dec743b4210`
`insightName`	string	Required	Name of the associated insight created in Tomorrow.io platform	`6 Hour Snow Accumulation`
`insightDescription`	string	Optional	Description of the insight created in Tomorrow.io platform	`Heavy snow accumulation of more than 6 inches expected`
`locationId`	string	Required	Identifier for the general location category based on feed coverage area	`us_continental`
`severity`	string	Required	Severity level of the event as defined in the insight	`severe`

Use Cases

GIS Integration

• Mapping weather events on interactive maps
• Geospatial analysis of weather patterns
• Integration with existing GIS workflows
• Real-time weather event visualization

Operational Monitoring

• Automated weather alert systems
• Infrastructure monitoring and protection
• Supply chain weather risk assessment
• Emergency response planning

Business Intelligence

• Weather impact analysis on operations
• Historical weather event reporting
• Custom dashboard integration
• Decision support systems

Research & Analytics

• Weather pattern research
• Climate impact studies
• Agricultural weather monitoring
• Environmental data analysis