The Visual Crossing Timeline Weather API can return significant historical weather and environmental events that occurred near a location.
These events include hail reports, tornado reports, wind-damage reports, earthquakes, and wildfire activity.
This makes it possible to answer questions such as:
- Was damaging hail reported near this property on a particular date?
- Were any tornadoes reported near this location?
- Was wind damage reported nearby during a storm?
- Were any earthquakes recorded near this location during a date range?
- Was there significant wildfire activity near this location?
Events can be returned alongside normal historical weather data, allowing applications to combine weather conditions and nearby event information in a single Timeline Weather API response.
The Visual Crossing Weather API provides programmatic access to historical weather, current conditions, forecasts, events, and other weather and environmental information.
To get started, sign up for a free Visual Crossing account and obtain your API key.
For the complete API reference, see the Timeline Weather API documentation.
Available event types
The Timeline Weather API can return several types of significant weather and environmental events.
| Event | type value | Coverage |
|---|---|---|
| Hail | hail | United States |
| Tornado | tornado | United States |
| Wind damage | wind | United States |
| Earthquake | earthquake | Global |
| Wildfire | wildfire | See wildfire documentation for current availability |
Different event types are derived from different sources and can contain different measurements and metadata.
Hail reports
Hail events represent reports of large or damaging hail.
In the response:
type=hail
Where available, the event value contains the reported hailstone size.
Hail reports may originate from storm spotters, members of the public, emergency services, weather stations, or other official reporting channels.
Tornado reports
Tornado events identify reported tornadoes.
In the response:
type=tornado
Where available, the event value can contain the Enhanced Fujita classification, such as EF0 through EF5.
Tornado classifications are not always available immediately. They can be added or revised after the National Weather Service completes a damage survey.
Wind-damage reports
Wind events represent reports of damage caused by severe wind that is generally not classified as tornado damage.
In the response:
type=wind
Where available, the event value contains the measured or estimated wind speed associated with the report.
Earthquake reports
Earthquake events are sourced from the United States Geological Survey and are available globally.
In the response:
type=earthquake
Where available, the event value contains the reported earthquake magnitude.
Earthquake magnitude should not be interpreted generically as a value on the Richter scale. Modern earthquake catalogs can use several magnitude methods depending on the event and available observations.
Wildfire events
The Timeline Weather API can also return nearby wildfire activity derived from satellite fire detections.
In the response:
type=wildfire
Wildfire events are different from individual storm and earthquake reports.
Instead of representing a single reported incident, multiple satellite detections can be analyzed together to identify, classify, and measure nearby wildfire activity.
Wildfire event information can include details such as:
- Location of the fire activity
- Distance from the requested location
- Time of detected activity
- Fire intensity
- Duration or persistence
- Classification of the detected activity
Wildfire events are currently a beta feature, and availability depends on the applicable Visual Crossing license.
Because wildfire events include additional fields and interpretation rules, see Wildfire Events in the Timeline Weather API for request examples, response fields, wildfire classification, intensity measurements, and usage guidance.
Where does event data come from?
Different event types use different underlying data sources.
US hail, tornado, and wind-damage reports are primarily sourced from NOAA and the National Weather Service Storm Prediction Center.
Earthquake reports are sourced from the United States Geological Survey.
Wildfire events are derived from satellite fire detections and associated processing used to identify and characterize nearby fire activity.
Depending on the event type, source information may originate from:
- Trained storm spotters
- Members of the public
- Weather stations
- Weather radar
- Emergency services
- Post-event damage surveys
- Automated seismic monitoring
- Satellite observations
Some events therefore become available very quickly, while others depend on manual reporting, later investigation, or subsequent observations.
Recent event data may change
Very recent event data should not always be considered final.
Storm reports may be:
- Added after the initial event
- Corrected
- Relocated
- Reclassified
- Supplemented with additional measurements
- Updated following a damage investigation
For example, a tornado may initially be reported without an Enhanced Fujita classification and later receive an EF rating after a damage survey.
Wildfire information can also evolve as new satellite detections are received and the extent or intensity of the detected fire activity changes.
Applications using recent event information should therefore allow for the possibility that recent records may be updated.
Enable events in a Timeline Weather API request
Events are not returned by default.
To request them, add:
include=events
to the Timeline Weather API request.
For example, this request retrieves events near a location for July 10 through July 12, 2020:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96,-96.02/2020-07-10/2020-07-12?unitGroup=us&include=events&key=YOUR_API_KEY
You can also retrieve events together with normal weather data:
include=days,events
For example:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96,-96.02/2020-07-10/2020-07-12?unitGroup=us&include=days,events&key=YOUR_API_KEY
This allows a single response to contain both daily weather and nearby events.
Event access depends on your subscription
Access to some event data depends on your Visual Crossing subscription or license.
If the requested event feature is not available for the current account, the API may return an error indicating that the feature is not included.
Wildfire events in particular are currently a beta feature and may not be available on all licenses.
Visual Crossing plans also include usage and request limits, so automated applications should operate within the limits of the account plan being used.
Select the event date range
Events use the dates supplied in the normal Timeline Weather API request.
There is no separate event-date parameter.
The Timeline request structure is:
/timeline/[location]/[date1]/[date2]
For example:
/timeline/Topeka,KS/2020-07-10/2020-07-12
requests events occurring during July 10 through July 12.
The end date is inclusive.
Events represent detected or reported events rather than predicted future events. Future dates therefore do not produce predicted hail, tornado, earthquake, or wildfire reports.
Events are associated with the requested location
The location supplied to the Timeline Weather API defines the center of the event search.
For example:
/timeline/Topeka,KS/2020-07-10
searches around the coordinates to which Topeka,KS resolves.
You can also specify latitude and longitude directly:
/timeline/39.0473,-95.6752/2020-07-10
Using coordinates is particularly useful when investigating events around:
- A property
- A facility
- A farm
- An insurance claim
- A utility asset
- A transportation route
- An incident location
Control the event search radius with maxDistance
For event types that use the standard proximity search, the maxDistance parameter controls how far from the requested location the API searches for matching events.
The value supplied to maxDistance is in meters regardless of the selected unitGroup.
For example:
maxDistance=25000
specifies a search distance of 25,000 meters, or 25 kilometers.
A request could look like:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0473,-95.6752/2020-07-10?unitGroup=us&include=events&maxDistance=25000&key=YOUR_API_KEY
maxDistance behavior
For standard event searches:
Requested maxDistance | Effective search radius |
|---|---|
Omitted, 0, or negative | 50 km |
1–50,000 | Requested distance in meters |
50,001–200,000 | Limited to 50 km |
Greater than 200,000 | HTTP 400 error |
The maximum effective standard event search radius is therefore 50 kilometers, approximately 31 miles.
The search is centered on the coordinates associated with the requested location.
Some specialized event types, including wildfire events, can have additional event-specific behavior. See the applicable event documentation when using those features.
Understand the event distance
Returned events can contain a distance value representing the distance from the requested location.
Unlike maxDistance, which is supplied in meters, the returned distance follows the selected unitGroup.
unitGroup | Returned event distance |
|---|---|
us | miles |
metric | kilometers |
uk | meters |
base | meters |
For example, with:
unitGroup=us
an event containing:
"distance": 12.4
is approximately 12.4 miles from the requested location.
Event response structure
In JSON results, matching events are associated with the applicable daily record.
A simplified response might look like:
{
"days": [
{
"datetime": "2020-07-10",
"events": [
{
"datetime": "2020-07-10T17:42:00",
"datetimeEpoch": 1594410120,
"type": "hail",
"latitude": 39.05,
"longitude": -95.68,
"distance": 12.4,
"value": 1.75,
"desc": "Hail report"
}
]
}
]
}
A day can contain multiple nearby events.
Days without matching event records may contain no events or an empty event collection depending on the response format and request.
Common event fields
Hail, tornado, wind, and earthquake event objects use a set of common fields.
Other event types, including wildfire events, can provide additional event-specific fields.
Common fields include:
| Field | Description |
|---|---|
type | Event type such as hail, tornado, wind, earthquake, or wildfire |
datetime | Local date and time associated with the event |
datetimeEpoch | Event time expressed as Unix epoch seconds |
latitude | Latitude of the reported or detected event |
longitude | Longitude of the reported or detected event |
distance | Distance from the requested location |
value | Event-specific measurement or classification where applicable |
desc | Optional event description |
Not every source supplies every field.
For wildfire-specific properties, see Wildfire Events in the Timeline Weather API.
Understand the value field
For the traditional storm and earthquake event types, the meaning of value depends on the event type.
| Event type | Meaning of value |
|---|---|
hail | Reported hailstone size |
wind | Reported or estimated wind speed |
tornado | Enhanced Fujita classification where available |
earthquake | Reported earthquake magnitude |
Wildfire events contain their own fire-specific intensity and classification information and should be interpreted using the dedicated wildfire documentation.
Hail units
Hail size is converted according to the selected unit group.
| Unit group | Hail value |
|---|---|
us | inches |
metric | millimeters |
uk | millimeters |
Wind units
Wind values are also converted according to the selected unit group.
| Unit group | Wind value |
|---|---|
us | mph |
metric | km/h |
uk | mph |
base | m/s |
Tornado classifications and earthquake magnitudes are not unit-converted.
Use datetimeEpoch for an absolute event time
Event records can include both:
datetime
and:
datetimeEpoch
datetime represents the event time in the applicable local time zone.
datetimeEpoch represents the event time as Unix epoch seconds and provides an unambiguous timestamp.
It is particularly useful when:
- Comparing events across time zones
- Sorting events chronologically
- Joining event records to other time-series data
- Storing event timestamps in a database
For more information about timestamps and time zones, see Dates and Times in the Weather API.
Retrieve events together with historical weather
One of the advantages of the Timeline Weather API is that nearby event information can be retrieved together with the weather conditions for the same period.
For example:
include=days,hours,events
can return daily weather, hourly weather, and nearby events in one response.
A request might look like:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Topeka,KS/2020-07-10?unitGroup=us&include=days,hours,events&maxDistance=25000&key=YOUR_API_KEY
This is useful when investigating the conditions associated with an event.
For example, an insurance or risk application might retrieve:
- Nearby hail reports
- Reported hail size
- Event distance
- Temperature
- Precipitation
- Wind speed
- Wind gust
- Pressure
- Other weather conditions
for the same time period.
For wildfire investigations, the same general principle applies: wildfire event information can be examined together with the weather conditions around the affected location.
Retrieve events in CSV format
The Timeline Weather API can also return CSV.
Add:
contentType=csv
to the request.
For example:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-07-22?unitGroup=us&include=events&contentType=csv&key=YOUR_API_KEY
CSV can be useful when importing event data into:
- Microsoft Excel
- Google Sheets
- Databases
- Business-intelligence tools
- Data-processing applications
JSON is generally more convenient for applications that need to preserve nested relationships between days and multiple events.
Example in Python
The following Python example retrieves nearby event reports:
import os
import requests
api_key = os.environ.get(
"VISUAL_CROSSING_API_KEY"
)
if not api_key:
raise RuntimeError(
"VISUAL_CROSSING_API_KEY is not set"
)
location = "39.0473,-95.6752"
start_date = "2020-07-10"
end_date = "2020-07-12"
url = (
"https://weather.visualcrossing.com/"
"VisualCrossingWebServices/rest/services/timeline/"
f"{location}/{start_date}/{end_date}"
)
params = {
"key": api_key,
"unitGroup": "us",
"include": "events",
"maxDistance": 25000,
"contentType": "json"
}
response = requests.get(
url,
params=params,
timeout=20
)
response.raise_for_status()
weather = response.json()
for day in weather.get("days", []):
for event in day.get("events", []):
print(
event.get("datetime"),
event.get("type"),
event.get("distance"),
event.get("value"),
event.get("desc")
)
Because not every day contains an event, the example uses:
day.get("events", [])
to safely handle days without matching event records.
Example: checking for hail near a property
Suppose you want to determine whether hail was reported near a property on a particular date.
You can query the property’s latitude and longitude:
/timeline/38.9697,-77.385/2026-06-15
and add:
include=events
plus an appropriate search radius:
maxDistance=16000
The returned events records can then be filtered for:
type=hail
The event’s distance indicates how far the report occurred from the requested property, and value can contain the reported hail size where available.
Example: checking for wildfire activity near a location
Wildfire activity can also be requested through Timeline events.
For example, an application can query a property, facility, or other location and determine whether satellite-observed wildfire activity occurred nearby during the requested period.
Wildfire events should not be interpreted exactly like individual storm reports. A wildfire event can represent multiple related satellite detections that have been grouped and analyzed to describe nearby fire activity.
The wildfire response includes additional information designed to help answer questions such as:
- How close was the fire?
- When was the strongest detected activity?
- How intense was the detected fire activity?
- How persistent was the activity?
- Does the activity appear consistent with wildfire or another persistent heat source?
For the full request syntax and field definitions, see Wildfire Events in the Timeline Weather API.
Events are different from weather alerts
Historical events and weather alerts serve different purposes.
Events describe significant weather or environmental activity that has occurred or been detected, such as:
hail
tornado
wind
earthquake
wildfire
Weather alerts represent watches, warnings, advisories, and other official alert products issued by weather authorities.
To retrieve alerts, use:
include=alerts
rather than:
include=events
An application can request multiple sections in the same Timeline Weather API request where applicable.
Common event-query patterns
To find events around a property:
/timeline/[latitude],[longitude]/[date]?include=events
To search within 10 km for applicable proximity-based events:
maxDistance=10000
To retrieve weather and events:
include=days,events
To investigate hourly conditions around an event:
include=days,hours,events
To retrieve event data for use in a spreadsheet:
include=events&contentType=csv
Choosing the right event documentation
This article provides an overview of the event system and the common hail, tornado, wind, earthquake, and wildfire event types.
For specialized event types, use the dedicated documentation when available.
In particular, wildfire events include substantially more event-specific processing and metadata than traditional storm reports.
See:
Wildfire Events in the Timeline Weather API
for detailed information about satellite detections, event grouping, intensity measures, classification, and wildfire-specific fields.
Going further
Weather and environmental event data can support applications involving:
- Insurance claims
- Property risk
- Severe-weather analysis
- Wildfire risk and impact analysis
- Damage assessment
- Transportation
- Utilities
- Agriculture
- Emergency management
- Historical event research
- Infrastructure monitoring
Because events can be returned alongside normal Timeline Weather API data, applications can examine not only whether a significant event occurred nearby but also the weather conditions surrounding that event.
The Visual Crossing Weather API provides programmatic access to historical weather, current conditions, forecasts, events, alerts, and other weather information.
For interactive access to weather datasets, see Visual Crossing Weather Data.
If you haven’t created an account yet, sign up for a free Visual Crossing account.
For detailed Timeline request parameters and response structures, see the Timeline Weather API documentation.
Summary
The Timeline Weather API can retrieve significant weather and environmental events near a requested location using:
include=events
Available event types include hail, tornado, wind damage, earthquakes, and wildfire activity.
Traditional event reports can include information such as:
- Event type
- Event time
- Latitude and longitude
- Distance from the requested location
- Event-specific measurement or classification
- Event description
Wildfire events extend this model with additional information derived from satellite fire detections and should be interpreted using the dedicated Wildfire Events in the Timeline Weather API documentation.
Events can also be retrieved together with historical weather, hourly conditions, and other Timeline Weather API data, making it possible to investigate both the occurrence of an event and the weather conditions surrounding it.