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:
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=csvData sources and report availability
The primary source for US hail, tornado, and wind-damage reports is the NOAA/NWS Storm Prediction Center (SPC). Earthquake reports are sourced from the United States Geological Survey (USGS).
Storm reports may be based on information from trained spotters, members of the public, weather stations, radar, and post-event damage investigations. Because many reports are collected or reviewed manually, the most recent several days may be incomplete. Reports—particularly tornado classifications—can also be revised as the National Weather Service completes its damage surveys.
Enabling events in a request
Events are not returned by default. To include them, add events to the include parameter:
&include=eventsYou can combine events with other sections of the Timeline API response:
&include=days,eventsIn JSON responses, matching events are returned in the events array of the applicable day. Each event is assigned to the day on which it occurred using the requested location’s local time zone, unless another time zone is specified in the request.
Note: Access to weather events depends on your subscription plan. If your plan does not include events, the API will return an error indicating that the feature is not available for the current subscription.
Selecting the date range
Events use the same date range as the rest of the Timeline API request. There is no separate event date parameter. For example:
/timeline/{location}/{date1}/{date2}The request returns matching events for the requested dates, including date2. Dates are interpreted in the local time zone of the requested location unless the timezone parameter specifies otherwise.
- Events contain historical reports only. Future dates do not produce future event reports.
- Each event is placed in the
eventsarray of the day matching its local date. - Events outside the requested date range are not returned.
- Reports from the most recent several days may be incomplete and may change as additional information becomes available.
- Standard Timeline API date-range and query-cost limits apply.
Setting the event search radius
The maxDistance parameter controls how far from the requested location the API searches for events.
| Behavior | Value |
|---|---|
| Request units | Meters. Input values are always interpreted as meters and are not scaled according to the requested unitGroup. |
| Default when omitted, zero, or negative | Uses the maximum event search radius of 50 kilometers. |
| Maximum event search radius | 50,000 meters, equivalent to 50 kilometers or approximately 31 miles. Larger permitted values are limited to 50,000 meters. |
| Absolute request maximum | Values greater than 200,000 meters return an HTTP 400 error. |
Response distance units | Miles for unitGroup=us, kilometers for unitGroup=metric, and meters for unitGroup=uk or unitGroup=base. |
Effective event search radius
Requested maxDistance | Effective event search radius |
|---|---|
Omitted, 0, or a negative value | 50 kilometers |
1–50,000 | The requested distance in meters |
50,001–200,000 | 50 kilometers; the value is silently limited to 50,000 meters |
Greater than 200,000 | HTTP 400 error |
For example, the following request searches for events within 25 kilometers of the requested location:
&maxDistance=25000&include=eventsThe event filter uses a circular search radius. Internally, the API first performs a bounding-box database search for efficiency and then calculates the exact spherical distance of each candidate event from the requested point. Events outside the requested circular radius are excluded.
For latitude-and-longitude queries, the search is centered on the supplied coordinates. For a city, address, or other geocoded location, the search is centered on the latitude and longitude to which the location resolves.
Event response fields
Each object in a day’s events array can contain the following fields:
| Field | Description |
|---|---|
type | Event type, such as hail, tornado, wind, or earthquake. |
datetime | Local date and time of the event. |
datetimeEpoch | Event time expressed as Unix epoch seconds. |
latitude | Latitude of the reported event. |
longitude | Longitude of the reported event. |
distance | Distance from the requested location, converted according to the requested unit group. |
value | Event-specific measurement or classification, where available. |
desc | Optional description supplied with the report. |
Meaning of the value field
| Event type | Meaning of value |
|---|---|
hail | Reported hailstone size, converted according to the requested unit group: inches (`us`) / mm (`metric`, `uk`) |
wind | Estimated wind speed: mph (`us`, `uk`) / kph (`metric`) / m/s (`base`) |
tornado | Enhanced Fujita scale classification, generally from EF0 through EF5. This value is not unit-converted. |
earthquake | Reported earthquake magnitude on the Richter Scale. This value is not unit-converted. |
Some fields may be omitted when the source report does not provide the corresponding value or description.
Example JSON response
{
"days": [
{
"datetime": "2020-07-10",
"tempmax": 92.1,
"events": [
{
"datetime": "2020-07-10T17:42:00",
"datetimeEpoch": 1594410120,
"type": "hail",
"latitude": 39.05,
"longitude": -95.68,
"distance": 12.4,
"value": 4.5,
"desc": "Hail 4.5 inches reported 3 SW of Topeka"
}
]
}
]
}Retrieving events in CSV format
The Timeline API also supports retrieving events in CSV format:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-07-22?unitGroup=us&key=YOUR_API_KEY&include=events&contentType=csvCSV cannot represent the full hierarchical structure available in JSON. When building an application that combines daily weather data with multiple events per day, JSON is generally the easier format to process.