The Timeline Weather API includes the ability to include storm reports and other significant weather and environmental events that have occurred near to a place of interest. These events can include earthquakes, hail, tornado and wind damage. When found, events are are included in the daily results of the Weather API.
What kind of reports are available?
There can be a number of different types of events. The following is the list of the main event types. In parentheses we include the type field that will be added to events in the output result.
Hail reports (hail)
Hail reports are reports of large or damaging hail. The reports often include the size of the hail reported. These are currently available for the United States.
Earthquake reports (earthquake)
Earthquake reports are collected by the United States Geological Survey and are available for the whole globe. We include only earthquakes of magnitude 2.5 or higher to avoid cluttering the data with many additional data points.
Tornado reports (tornado)
Tornado reports are collected for the United States and typically include an estimate of the strength on the Enhanced Fujita Scale from 0 to 5
Wind damage reports (wind)
Wind damage reports represent reports of damage from wind (typically not associated with tornado damage). In addition to the report of damage, these reports will often include the estimated wind speed.
How are these reports collected?
Events can come from a variety of sources including automated reporting (such as seismographs for earthquakes and weather stations or weather radar for weather events). In addition, the events can be reported by trained observers (often referred to as trained spotters) or even members of the public. In some cases, such as severe weather including tornadoes, the weather service will send out investigators to collect evidence and assess damage.
As many of the events are not automated and rely on manually entered reports, the data can take a number of days to be entered into the source system. In addition, when the event is subject to an investigation, the data for the event can change over time as more information is collected.
How to add events to the results of the timeline API
Events are not included in the default timeline weather API queries. To include them, you must enable the ‘events’ section for the request. You should also select any other sections you would like information for.
For example the following retrieves weather events for Herndon,VA,USA for 22nd July 2020 in CSV format:
Weather Events are currently available in our monthly and enterprise plans. See our pricing for more details.
When you include them, you will find any events for a particular day listed as an array of events in the events property of the day instance. For example, the following Timeline API request will include weather events:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96%2C-96.02/2020-7-10/2020-7-12?unitGroup=us&key=YOUR_API_KEY&include=obs,eventsHere we see a hail report for hailstones of size 4.5 includes near Topeka, Kansas on July 10th 2020:
Events will include a event type, the datetime of the event, the location of the event (expressed as a latitude & longitude), a distance from the requested location to the event. Finally if the event included a description or value (such as size, magnitude, wind speed or tornado class) they will be reported too.
How to retrieve storm reports in CSV format
The Timeline Weather API supports retrieving storm reports in CSV format for easy import into tools such as Microsoft Excel, Google Sheets and databases. To retrieve the storm events for a location in CSV format you can use the contentType parameter:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-07-22?unitGroup=us&key=YOUR_API_KEY&include=events&contentType=csv