Tomorrow.io LLM-Friendly Weather API Documentation

Overview

The On-Demand Events API provides real-time weather insights and forecasts for specific locations. This API allows users to retrieve valuable weather information by providing location details and weather conditions to be met, depending on the data layer.

Key Features

• Real-time insights: Generate weather insights and forecasts on-demand
• Location-based analysis: Support for point locations and geometric areas
• Flexible conditions: Define custom weather thresholds using rules or existing insights
• Timeline format: Receive chronological event data with activation states
• Multiple trigger methods: Use rules-based conditions or predefined insight IDs
• Detailed metadata: Get actual values and trigger values for each event

Token Usage Mechanism:

• Point location Request: 1 token
• Polygon Request: 10 tokens
• Token optimization: Use point locations for cost-effective monitoring
• Historical events Timeline: Access historical data for trend analysis

Authentication

All On-Demand Events API requests 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

Generate Events Timeline

Generate On-Demand Events Timeline

https://api.tomorrow.io/v4/events-timeline?apikey={apikey}

Request Body Parameters

Parameter	Type	Required	Description	Example
`location`	object	Required	Location specification using either locationId or geometry coordinates	`{"geometry": {"type": "Point", "coordinates": [-73.890, 40.768]}}`
`insight`	object	Required	Weather conditions to be met, specified using rules or existing insight ID	`{"rules": "temperature > 30"} or {"insightId": "uuid"}`

Location Options

Parameter	Type	Required	Description	Example
`locationId`	string	Optional	Specify the location using either geometry or locationId (JSON format)	`ID`
`geometry`	object	Optional	GeoJSON geometry object defining the location	`{"type": "Point", "coordinates": [-73.890, 40.768]}`

Insight Options

Parameter	Type	Required	Description	Example
`rules`	string	Optional	Custom weather conditions using rules syntax (e.g., "temperature > 30")	`temperature > 30`
`conditions`	object	Optional	Structured conditions object (alternative to rules)	`{"...": "..."}`
`insightId`	string	Optional	ID of an existing insight created in Tomorrow.io platform	`d3dabf22-9877-4688-b2b9-e71eaf521838`

Example Request Body

{
  "location": {
    "geometry": {
      "type": "Point",
      "coordinates": [-73.890, 40.768]
    }
  },
  "insight": {
    "rules": "temperature > 30"
  }
}

Example Request (cURL)

curl -X POST "https://api.tomorrow.io/v4/events-timeline?apikey=YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "location": {
      "geometry": {
        "type": "Point",
        "coordinates": [-73.890, 40.768]
      }
    },
    "insight": {
      "rules": "temperature > 30"
    }
  }'

Response Example

{
  "data": {
    "eventsTimeline": {
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.89,
          40.768
        ]
      },
      "items": [
        {
          "from": "2025-07-07T05:00:00Z",
          "active": false,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 29.3
          },
          "actualTriggerValues": {
            "temperature": 29.3
          }
        },
        {
          "from": "2025-07-07T16:00:00Z",
          "active": true,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 30.9
          },
          "actualTriggerValues": {
            "temperature": 30.9
          }
        },
        {
          "from": "2025-07-07T21:00:00Z",
          "active": false,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 29.9
          },
          "actualTriggerValues": {
            "temperature": 29.9
          }
        },
        {
          "from": "2025-07-08T15:00:00Z",
          "active": true,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 34
          },
          "actualTriggerValues": {
            "temperature": 34
          }
        },
        {
          "from": "2025-07-09T01:00:00Z",
          "active": false,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 30
          },
          "actualTriggerValues": {
            "temperature": 30
          }
        },
        {
          "from": "2025-07-09T14:00:00Z",
          "active": true,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 33.7
          },
          "actualTriggerValues": {
            "temperature": 33.7
          }
        },
        {
          "from": "2025-07-10T00:00:00Z",
          "active": false,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 29.8
          },
          "actualTriggerValues": {
            "temperature": 29.8
          }
        },
        {
          "from": "2025-07-10T17:00:00Z",
          "active": true,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 30.7
          },
          "actualTriggerValues": {
            "temperature": 30.7
          }
        },
        {
          "from": "2025-07-10T20:00:00Z",
          "active": false,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 29
          },
          "actualTriggerValues": {
            "temperature": 29
          }
        },
        {
          "from": "2025-07-11T17:00:00Z",
          "active": true,
          "activeAreaRatio": {
            "min": 1,
            "max": 1
          },
          "actualValues": {
            "temperature": 31.7
          },
          "actualTriggerValues": {
            "temperature": 31.7
          }
        }
      ],
      "itemsStartTime": "2025-07-07T05:00:00Z",
      "itemsEndTime": "2025-07-11T17:00:00Z"
    }
  }
}

Response Object Structure

The response contains an events timeline with detailed information about when weather conditions are met or not met at the specified location.

Events Timeline Object

Parameter	Type	Required	Description	Example
`geometry`	object	Required	GeoJSON geometry of the location used for analysis	`{"type": "Point", "coordinates": [-73.89, 40.768]}`
`items`	array	Required	Array of timeline items showing condition changes over time	`[{...timeline items...}]`
`itemsStartTime`	string	Required	UTC timestamp of the first timeline item (ISO 8601 format)	`2025-07-07T05:00:00Z`
`itemsEndTime`	string	Required	UTC timestamp of the last timeline item (ISO 8601 format)	`2025-07-11T17:00:00Z`

Timeline Item Properties

Parameter	Type	Required	Description	Example
`from`	string	Required	UTC timestamp when this condition state begins (ISO 8601 format)	`2025-07-07T16:00:00Z`
`active`	boolean	Required	Whether the specified conditions are met during this time period	`true`
`activeAreaRatio`	object	Required	Ratio of the area where conditions are active (min/max values)	`{"min": 1, "max": 1}`
`actualValues`	object	Required	Actual weather values at this time point	`{"temperature": 30.9}`
`actualTriggerValues`	object	Required	Weather values that triggered the condition evaluation	`{"temperature": 30.9}`

Example Use Cases

The On-Demand Events API is a versatile tool with various use cases. It can be employed in scenarios where real-time weather insights are crucial, such as:

Weather Forecasting

Users can retrieve detailed weather forecasts for specific locations, allowing them to plan activities, events, or operations accordingly.

• Event planning and scheduling
• Agricultural planning and monitoring
• Outdoor activity recommendations

Environmental Monitoring

Researchers and environmentalists can leverage the API to monitor weather conditions in specific geographic areas for climate studies.

• Climate research and analysis
• Environmental impact studies
• Ecosystem monitoring

Emergency Preparedness

Emergency response teams can use the API to monitor weather conditions and receive alerts for potential disasters, helping them plan response strategies.

• Disaster preparedness planning
• Emergency response coordination
• Risk assessment and mitigation

Agriculture and Farming

Farmers can use the API to receive weather insights, enabling better crop-making regarding planting, irrigation, and harvesting.

• Crop planning and optimization
• Irrigation scheduling
• Harvest timing decisions

Error Handling

The API returns appropriate HTTP status codes and error messages for various scenarios. Handle these errors gracefully in your application.

Common Error Responses

Parameter	Type	Required	Description	Example
`400001`	Invalid Body Parameters	Optional	Request body parameters are invalid or malformed	`Invalid location or insight format`
`404001`	Not Found	Optional	Specified insight ID could not be found	`Insight ID does not exist`
`401`	Unauthorized	Optional	Invalid or missing API key	`API key authentication failed`

Error Response Example

{
  "code": 404001,
  "type": "Not Found",
  "message": "The insight associated with the request could not be found: d3dabf22-9877-4688-b2b9-e71eaf521838."
}

Notes

Important: On-Demand Events is currently supported only for the metric system.

Note: This API provides real-time analysis based on current weather data and forecasts. Results may vary based on data availability and forecast accuracy.