Severe weather season is continuing this week, with several days of severe weather forecast across the central and southeastern US. Convective outlooks provide insight into the potential for severe weather for up to a week out, giving the probabilities of areas seeing severe weather such as large hail, damaging winds, and even tornadoes.
We continue our severe weather product series where we highlight severe weather-related features of the Aeris API and Aeris Maps platform. Last time, we discussed our storm cell features and how they provide information on where storms are currently and where they’re heading. This time, we’re going to look at convective outlooks in greater depth.
Our convective outlook endpoint provides access to the convective weather outlooks issued by the Severe Prediction Center (SPC). General convective outlooks are available for the next eight days while hail, wind and tornado outlooks are only available for the current day.
Convective Outlook Map Layers
Our Aeris Maps Platform (AMP) offers a map layer for the SPC convective outlooks to be rendered as static maps or to be used as tiles with any mapping library. For example, here’s a static map of current categorical convective outlooks for Wednesday, April 26, 2017:
|
1 |
https://maps.aerisapi.com/[client_id]_[client_key]/flat-dk,convective,cities-dk/700x400/38,-96,4/current.png |
Notice the use of the offset current, which tells AMP to use the current convective outlook and correlates to SPC’s outlook for day one. For tomorrow’s outlook, or SPC day two, use an offset of +1day or +1days:
|
1 |
https://maps.aerisapi.com/[client_id]_[client_key]/flat-dk,convective,cities-dk/700x400/38,-96,4/+1day.png |
Below is a summary of the SPC day and the corresponding AMP offset value to request:
| SPC Day | AMP Offset |
|---|---|
| Day 1 | current or +0days |
| Day 2 | +1day |
| Day 3 | +2days |
| Day 4 | +3days |
| Day 5 | +4days |
| Day 6 | +5days |
| Day 7 | +6days |
| Day 8 | +7days |
The day 1 hail, tornado, and damaging wind probabilities are available by using one of the following layer names with the current offset:
| Hazard | AMP Layer |
|---|---|
| Hail | convective-hail |
| Tornado | convective-torn |
| Damaging Winds | convective-wind |
|
1 |
https://maps.aerisapi.com/[client_id]_[client_key]/flat-dk,convective-torn,cities-dk/700x400/38,-96,4/current.png |
Convective Outlook Data
If you need access to the raw outlook data for custom implementations, our Aeris Weather API can be used to query the convective outlooks directly with considerable flexibility.
Active Convective Outlooks
One common request is to fetch the latest convective outlooks across the US. This can be useful to display in a chart or use as the trigger for an alarm or notification. Using a combination of the search action and filters you can obtain the categorical outlooks for the current day (SPC Day 1):
|
1 |
/convective/outlooks/search?filter=cat,day1&sort=code |
In the above example, we used filter=cat,day1 to limit the results to categorical outlooks for day 1. The sort=code parameter will ensure the results are sorted with the least significant categories first. To reverse this order with the most significant categories first, use sort=code:-1.
When integrating convective outlooks into a mapping library, you may need the polygons associated with the outlooks to render on the map. To have the API include this polygon data in the result, add geo to the list of filters:
|
1 |
/convective/outlooks/search?filter=cat,day1,geo&sort=code |
The resulting API response will contain a geoPoly attribute which contains the polygons in GeoJSON. To have the entire result returned as GeoJSON instead of the standard JSON API response, add format=geojson :
|
1 |
/convective/outlooks/search?filter=cat,day1,geo&sort=code&format=geojson |
To fetch the hail, tornado or damaging wind outlooks, use the appropriate filter. For example, for hail outlooks:
|
1 |
/convective/outlook/search?filter=hail |
Convective Outlooks for a Location
With the convective outlook endpoint, you can request the convective outlooks a location may be contained within, if any. This is useful for highlighting convective hazards on a local weather view or to alert client facilities that reside in a medium or higher convective hazard.
To determine the current day’s convective categorial hazards for Atlanta, GA, use a query similar to:
|
1 |
/convective/outlook/contains?p=atlanta,ga&filter=cat,day1 |
Alternatively, if you pass just a location instead of using the contains action, then the API will perform the contains action automatically:
|
1 |
/convective/outlook/atlanta,ga?filter=cat,day1 |
Cities Within Outlooks
A unique feature of the convective outlooks endpoint is the ability to return a list of cities that are within a specified outlook. Simply pass the outlook’s unique id to the endpoint via the affects action for the outlook you want the list of locations within. We use this method for our convective outlook page to display a list of major cities for each category, whose query would be similar to:
|
1 |
/convective/outlook/affects?p=348584c3e3f05dcf19fdfdac2b92a020&limit=5 |
…where 348584c3e3f05dcf19fdfdac2b92a020 is the id attribute from the convective outlook that you are fetching the affected cities for.
The following simple JavaScript code snippet demonstrates fetching the convective outlooks for the day and listing the top five affected cities for each. You can view a demo of the similar code in action or grab the complete example code from our examples repository:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
<div class="cities"></div> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script> <script> // url to fetch the current day convective outlooks var convectiveSrcUrl = 'http://api.aerisapi.com/convective/outlook/search?filter=cat,day1&sort=code:-1&client_id=CLIENTID&client_secret=CLIENTSECRET'; // url to fetch the cities affected by a convective outlook var affectsSrcUrl = 'http://api.aerisapi.com/convective/outlook/affects?p={id}&limit=5&client_id=CLIENTID&client_secret=CLIENTSECRET'; // start by fetching the convective outlooks jQuery.getJSON(convectiveSrcUrl, function (data) { data.response.forEach(function (outlook) { var id = outlook.id; var type = outlook.details.risk.name.replace(/\b\w/g, function(l){ return l.toUpperCase() });; // insert the outlook id into the affects url var url = affectsSrcUrl.replace('{id}', id); // fetch the cities within the url jQuery.getJSON(url, function (cities) { // step through the cities and add to list var citiesList = []; cities.response.forEach(function(city) { // proper case the city and state var name = city.place.name.replace(/\b\w/g, function(l){ return l.toUpperCase() }); name += ', ' + city.place.state.toUpperCase(); citiesList.push(name); }); // lets add the cities for this outlook category to the page $('div.cities').append('<div class="type">' + type + "</div>" + '<div class="city-list">' + citiesList.join("<br/>\n") + '</div><br/>'); }); }); }); </script> |
Get started with Convective Outlooks
We’ve reviewed the many capabilities of the convective outlook datasets — from map layers to querying the data directly. Severe weather season is going strong, so get started with our free developer account to experiment with integrating convective outlook information to your own applications today!
No comments yet.
Be the first to respond to this article.