+27 87 310 6400 | products@afrigis.co.za
bclose

Weather Storms API

Retrieve current and historic weather storms feed as published by the South African Weather Service.

API DOCUMENTATION

1. Introduction

2. weather.tstorms.locationForecast

3. weather.tstorms.locationHistory

4. weather.tstorms.historicalDetails

5. weather.tstorms.feed

6. A note on ISO 8601 timestamps

7. AfriGIS status codes

 

1. Introduction

AfriGIS Weather Storms API exposes the South African Weather Service (SAWS) thunderstorms data feed as an Application Programming Interface (API). It allows you to easily access predicted (current to one hour into the future) and historical weather data at a given location.

Typical users might be:

  • Insurance companies, wanting to warn clients of impending thunderstorms, to possibly move their vehicles out of the way of the storm
  • Insurance companies, wanting to verify client claims of hail or lightning damage against historical data
  • Courier companies, wanting to determine alternative routes in order to calculate alternative schedules
  • Municipalities, wanting to issue warnings to residents in affected areas

The measurement of storm intensity (dBZ)

dBZ versus Rainrate

dBZRate (mm/hour)Rate (inches/hour)Intensity
50.07< 0.01Hardly noticeable
100.15< 0.01Light mist
150.30.01Mist
200.60.02Very light
251.30.05Light
302.70.10Light to moderate
355.60.22Moderate rain
4011.530.45Moderate rain
4523.70.92Moderate to heavy
5048.61.90Heavy
551004Very heavy/small hail
602058Extreme/moderate hail
6542116.6Extreme/large hail

Source: Wikipedia

You may want to review the Wikipedia page for dBZ for more information.

 

2. weather.tstorms.locationForecast

With this REST method, you can retrieve the thunderstorm forecast for the next 60 minutes at a given location. You can specify a buffer distance that will be added to this location. We will return a boolean value indicating whether there is any overlap with a predicted storm, and if so, what the maximum storm intensity will be. The forecast (D below) is a combination of the SAWS current storm (A) and the predictions for the next 30 minutes (B) and 60 minutes (C). The maximum storm intensity of D is the maximum of A, B and C.

Storm forecast example

Open to view larger image

Optionally, you can specify a higher dBZ threshold than the default of 30 dBZ, in which case only more intense storms will be considered.

Parameters

Required Parameters

location (string: double, double) – the decimal degrees coordinate of the location to query. Note that the order is latitude then longitude, separated by a comma.

Optional Parameters

location_buffer (integer) – the location geometry will be extended outwards by this number of metres, to ensure that nearby storms are also considered. Default = 0 metres, maximum = 1000000 metres (1000 km).

dbz (float) – a minimum thunderstorm intensity to consider. Storms with an intensity less than this parameter will be ignored. Default = 30 dBZ (the minimum)

Sample Request:

In this example we request the storm forecast for 300 metres around a given location (-31.2347, 31.21876), only for moderate to heavier storms.

GET https://saas.afrigis.co.za/rest/2/weather.tstorms.locationForecast/AUTH_PARAMS/?location=-31.2347,31.21876&location_buffer=300&dbz=45

Please note that this is a time-sensitive API call, therefore the sample response will not match the current response.

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description

If code = 200, the result object will contain the tstorm element:

  • tstorm (boolean) – indicates whether the location geometry including its buffer overlaps any storm forecast geometries, or not.
If tstorm = true, the result object will also contain these elements:
  • closest – containing a summary of the storms data, at the point of minimum distance, with:
    • distance (integer) – the closest that the storm approached (in metres)
    • dbz (float) – the storm intensity at this closest point
  • strongest – containing a summary of the storms data, at the point of maximum intensity, with:
    • dbz (float) – the maximum storm intensity
    • distance (integer) – the distance (in metres) at this maximum point
If there are no results at all for the specified time period, tstorm will be false and there will be no other elements in the JSON:

Click to expand Empty Response

 

3. weather.tstorms.locationHistory

With this REST method, you can retrieve thunderstorm history at a given location and time. You can specify a buffer distance that will be added to this location. We will return a boolean value indicating whether there is any overlap with a storm, and if so, a summary of what the closest distance and the maximum storm intensity was.

In the image below, A and B are two different storms, at times t0, t1, t2 and t3. Only instances overlapping the circular buffer around different query locations (Loc 1, Loc 2, Loc 3, Loc 4) will return a distance (a – g) and the storm intensities. Note that g = 0 because Loc 3 is within Bt3. No results are returned for Loc 4.

Storms API example

Open to view larger image

Optionally, you can specify a higher dBZ threshold than the default of 30 dBZ, in which case only more intense storms will be considered.

Parameters

Required Parameters

location (string: double, double) – the decimal degrees coordinate of the location to query. Note that the order is latitude then longitude, separated by a comma.

time_start and time_end (ISO 8601 string) – only thunderstorms with a timestamp greater than time_start and less than time_end will be considered. The maximum time span is 31 days; larger time spans will return a 400 Bad Request error.
Example = 2016-08-21T12:00:00+02:00

Optional Parameters

location_buffer (integer) – the location geometry will be extended outwards by this number of metres, to ensure that nearby storms are also considered. Default = 0 metres, maximum = 1000000 metres (1000 km).

dbz (float) – a minimum thunderstorm intensity to consider. Storms with an intensity less than this parameter will be ignored. Default = 30 dBZ (the minimum)

Sample Request:

In this example we request the history for 300 metres around a given location (-33.7083, 23.0083), for a week, only for moderate storms.

GET https://saas.afrigis.co.za/rest/2/weather.tstorms.locationHistory/AUTH_PARAMS/?location=-33.7083,23.0083&location_buffer=300&time_start=2016-09-11T15:00:00Z&time_end=2016-09-18T00:00:00Z&dbz=40

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description

The first thing you should check is code – see the AfriGIS status codes section below.

If code = 200, the result object will contain the tstorm element:

  • tstorm (boolean) – indicates whether the location geometry including its buffer overlaps any storm geometries, or not.
If tstorm = true, the result object will also contain these elements:
  • closest – containing a summary of the storms data, at the point of minimum distance, with:
    • distance (integer) – the closest that the storm approached (in metres)
    • dbz (float) – the storm intensity at this closest point
  • strongest – containing a summary of the storms data, at the point of maximum intensity, with:
    • dbz (float) – the maximum storm intensity
    • distance (integer) – the distance (in metres) at this maximum point
If there are no results at all for the specified time period, tstorm will be false and there will be no other elements in the JSON:

Click to expand Empty Response

 

4. weather.tstorms.historicalDetails

With this REST method, you can retrieve the full thunderstorm history (excluding the forecast) for a given time period. It returns each storm’s geometry, ellipse representation, centroid coordinates, speed and direction, age, cell_top and intensity.

You can optionally provide a location (and a buffer distance that will be added to this location), and the historical data will be filtered to only overlapping storms.

The ellipse representation of the storm is returned by default – for a glossary, see the diagram below. You can also optionally request the entire storm geometries (currently only GeoJSON format).

Storm geometries

Open to view larger image

Optionally, you can specify a higher dBZ threshold than the default of 30 dBZ, in which case only more intense storms will be considered.

Parameters

Required Parameters

time_start and time_end (ISO 8601 string) – only thunderstorms with a timestamp greater than time_start and less than time_end will be considered. The maximum time span is 31 days; larger time spans will return a 400 Bad Request error.
Example = 2016-08-21T12:00:00+02:00

Optional Parameters

location (string: double, double) – the decimal degrees coordinate of the location to query. Note that the order is latitude then longitude, separated by a comma. Default = the whole country.

location_buffer (integer) – the location geometry will be extended outwards by this number of metres, to ensure that nearby storms are also considered. Default = 0 metres, maximum = 1000000 metres (1000 km).

response_format (string) – the response result features will include a full storms geometry if this parameter is “GeoJSON”. Default = none, in which case, the geometry object will be excluded from the response.

dbz (float) – a minimum thunderstorm intensity to consider. Storms with an intensity less than this parameter will be ignored. Default = 30 dBZ (the minimum).

Optional HTTP Headers

Accept-encoding: gzip – if the response is large, the API will compress the response and add the Content-encoding: gzip header.

Sample Request:

In this example we request the historical details for 300 metres around a given location (31.21876, -31.2347), including the storm geometries, for a week, only for moderate storms.

GET https://saas.afrigis.co.za/rest/2/weather.tstorms.historicalDetails/AUTH_PARAMS/?location=-33.7083,23.0083&location_buffer=300&response_format=GeoJSON&time_start=2016-09-11T15:00:00Z&time_end=2016-09-18T00:00:00Z&dbz=40

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description

If code = 200, the result object will contain a JSON object, derived from the GeoJSON FeatureCollection spec, with:

  • type = “FeatureCollection”
  • features is an array, containing:
    • type = “Feature”
    • properties is an object, containing:
      • timestamp (ISO 8601 string) – the UTC time of the data feed from SAWS.
      • instance (integer) – an enumeration of the current or forecast instance:
        • 0 = now
        • 1 = 30min
        • 2 = 60min
      • latitude, longitude (double) – the coordinates of the centroid of the storm
      • speed, direction (float) – the speed in km per hour and direction (relative to true north) that the storm is travelling in
      • age (integer) – the time in seconds since the storm developed, up to the timestamp
      • cellTop (float) – the maximum height of the storm (measured at 30 dBZ)
      • dbz (float) – the storm intensity measured by the maximum radar reflectivity in dBZ
      • majorAxis (float) – the length of the ellipse representation in km,
      • minorAxis (float) – the length of the ellipse representation in km,
      • orientation (float) – of the major axis, relative to true north, in degrees.
      • distance (integer) – the distance in metres from the location. Note that distance is only given if the request parameter location was specified, otherwise it is excluded.
    • geometry is a GeoJSON Geometry object representing the full storm geometry, e.g.: {“type”:”Polygon”,”coordinates”:[[[[22.8595,-33.7637],[22.8839,-33.7637],[22.8891,-33.765],[22.8595,-33.7637]]]]}. Note that geometry is only given if the request parameter response_format = “GeoJSON”, otherwise it is excluded.
If there are no results at all for the specified time period, features will be an empty array, and there will be no other elements in the JSON:

Click to expand Empty Response

 

5. weather.tstorms.feed

With this REST method, the entire SAWS data feed is made available. It returns the current (and forecast) storms, including their geometry, ellipse representation, centroid coordinates, speed and direction, age, cell_top and intensity, for now, 30 minutes and 60 minutes. It only returns the data in the latest XML file from SAWS; if there are no storms in there, then none are returned.

You can optionally provide a location (and a buffer distance that will be added to this location), and the data feed will be filtered to only overlapping storms.

The ellipse representation of the storm is returned by default – for a glossary, see the diagram below. You can also optionally request the entire storm geometries (currently only GeoJSON format).

Storm geometries

Open to view larger image

Optionally, you can specify a higher dBZ threshold than the default of 30 dBZ, in which case only more intense storms will be considered.

Parameters

Required Parameters

None

Optional Parameters

location (string: double, double) – the decimal degrees coordinate of the location to query. Note that the order is latitude then longitude, separated by a comma. Default = the whole country.

location_buffer (integer) – the location geometry will be extended outwards by this number of metres, to ensure that nearby storms are also considered. Default = 0 metres, maximum = 1000000 metres (1000 km).

response_format (string) – the response result features will include a full storms geometry if this parameter is “GeoJSON”. Default = none, in which case, the geometry object will be excluded from the response.

dbz (float) – a minimum thunderstorm intensity to consider. Storms with an intensity less than this parameter will be ignored. Default = 30 dBZ (the minimum).

Optional HTTP Headers

Accept-encoding: gzip – if the response is large, the API will compress the response and add the Content-encoding: gzip header.

Sample Request:

In this example we request the storm feed for 300 metres around a given location (31.21876, -31.2347), including the storm geometries, only for moderate to heavier storms.

GET https://saas.afrigis.co.za/rest/2/weather.tstorms.feed/AUTH_PARAMS/?location=-31.2347,31.21876&location_buffer=300&response_format=GeoJSON&dbz=45

Please note that this is a time-sensitive API call, therefore the sample response will not match the current response.

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description

If code = 200, the result object will contain a JSON object, derived from the GeoJSON FeatureCollection spec, with:

  • type = “FeatureCollection”
  • features is an array, containing:
    • type = “Feature”
    • properties is an object, containing:
      • timestamp (ISO 8601 string) – the UTC time of the data feed from SAWS.
      • instance (integer) – an enumeration of the current or forecast instance:
        • 0 = now
        • 1 = 30min
        • 2 = 60min
      • latitude, longitude (double) – the coordinates of the centroid of the storm
      • speed, direction (float) – the speed in km per hour and direction (relative to true north) that the storm is travelling in
      • age (integer) – the time in seconds since the storm developed, up to the timestamp
      • cellTop (float) – the maximum height of the storm (measured at 30 dBZ)
      • dbz (float) – the storm intensity measured by the maximum radar reflectivity in dBZ
      • majorAxis (float) – the length of the ellipse representation in km,
      • minorAxis (float) – the length of the ellipse representation in km,
      • orientation (float) – of the major axis, relative to true north, in degrees.
      • distance (integer) – the distance in metres from the location. Note that distance is only given if the request parameter location was specified, otherwise it is excluded.
    • geometry is a GeoJSON Geometry object representing the full storm geometry, e.g.: {“type”:”Polygon”,”coordinates”:[[[[22.8595,-33.7637],[22.8839,-33.7637],[22.8891,-33.765],[22.8595,-33.7637]]]]}. Note that geometry is only given if the request parameter response_format = “GeoJSON”, otherwise it is excluded.
If there are no results at all for the specified time period, features will be an empty array, and there will be no other elements in the JSON:

Click to expand Empty Response

 

6. A note on ISO 8601 timestamps:

More information on Wikipedia

The timestamps in the SAWS data feed are in UTC/Zulu/GMT+0. This is most easily indicated in the timestamp as Z after the time portion i.e. “2016-08-20T12:00:00Z“. We will always return a timestamp in UTC. To specify an input time in SAST, you can use the time zone designators:

  • “+02:00”
  • “+0200”
  • “+02”

Alternatively, do not specify a time zone designator at all, and we will assume that you mean local time, i.e. SAST, e.g.

  • “2016-08-20T14:00:00+02:00”
  • “2016-08-20T14:00:00+0200”
  • “2016-08-20T14:00:00+02”
  • “2016-08-20T14:00:00”

Note that you should definitely URL-encode the + part of the timezone designator to %2B.

 

7. AfriGIS status codes

code is a standard element in the JSON response from any AfriGIS webservice, and you should check it before using the rest of the response.

codeDescriptionDetails
200SuccessHopefully the most common code - a response WILL be found in "result"
400Bad RequestThe request cannot be fulfilled due to bad syntax - missing parameters, perhaps.
401Unauthorised/ Authentication FailedThe username, password or HMAC provided was incorrect.
402Payment RequiredAuthorisation has failed because there are insufficient credits.
403ForbiddenAuthorisation has failed - the requested service is not permitted.)
418TimeoutsaasTime error - client time does not match server time.
502Bad GatewayThe underlying resources or web services are not currently available.
Project Details