1. Help Center
  2. Documentation
  3. AerisWeather API
  4. Reference
  5. Endpoints

AerisWeather API

Endpoint: lightning/threats

To access Lightning, Lightning Summary, Lightning Threats, lightning mapping features, or historical lightning data, select our Lightning Add-On when building your Flex subscription or contact us to add it to your existing plan.
Lightning Flash data and mapping layers can be accessed from your Flex subscription.

The lightning threats endpoint provides access to lightning nowcasts, providing up to 60 minutes of potential thunderstorm activity in 10-minute intervals. Lightning threats are available globally and based on Vaisala’s high-quality lightning data.

Base URL Path https://api.aerisapi.com/lightning/threats
Data Coverage Global
Included With Lightning Add-On
Update Interval Every 2 minutes

Supported Actions

The following actions are supported with the lightning/threats endpoint:

:id Requesting data by using the :id action is used for returning data for a particular item that has an ID associated with it. This is the primary method for requesting general weather information for a single location (observations, forecasts, advisories, etc.) as the location's name or a zip code serves as the id. Other endpoints may expect a certain value for the ID, such as storm cells whose ID value is a combination of the radar site identifier and unique identifier assigned to every storm cell. Refer to an endpoint's detailed documentation for specific information regarding how to use the :id action.
contains The contains action returns data that a specified location is contained within. This action is normally associated with endpoints that contain polygon data, allowing to return only the polygons a point / geometry is contained in. This action can be considered the opposite of the within endpoint.
closest The closest action will query the API for data that is closest to the requested place and return the results, if any, in order from closest to farthest. If no limit is provided in the request, then only the closest single result will be returned.

If your request does not return results, you may try setting or increasing the radius being used.
affects The affects action requests all places affected by a particular type of event, such as earthquake or storm cell. The query for places affected is unique for each endpoint it belongs to and can be a polygon (e.g., storm cell forecasts or warnings) or a circle with the center being the location of the event (e.g., earthquakes or fires). Instead of returning an array of objects specific to the endpoint, the affects action will always return an array of place objects in the same format as the within action on the places endpoint.

Note: Not all endpoints support this action, so refer to each endpoint's complete documentation to determine if supported and its usage.
route The route action returns data for points along a given route. This can be useful to obtain weather information along a transportation route, trails and more. The route is a series of locations, usually latitude/longitudes provided via the p query parameter or for longer routes via GeoJSON within a POST request. The route will return an array of GeoJSON points with the requested data for each point.

Supported Parameters

The following parameters are optional unless otherwise noted:

p p=:place Defines the location to query data for. Refer to the list of supported place value formats.
fields fields=:string Provides a comma separated list of values for the API to return. This parameter is often used to limit the amount of data returned. See Reducing Output.
for for=:string Returns the results starting for the time frame specified. The for parameter is an alias of the from, but useful to indicate a specific time versus a time range

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
for=tomorrow
for=friday
for=1302883980
for=MM/DD/YYYY
for=YYYY/MM/DD
for=+2hours
for=2017-02-27 5:00 PM
from from=:string Returns the results starting from the value specified. For best practices we recommend using the to parameter as well to define a specific time frame.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
from=tomorrow
from=friday
from=1302883980
from=MM/DD/YYYY
from=YYYY/MM/DD
from=+2hours
from=2017-02-27 5:00 PM
to to=:string Returns the results between now and the value specified. For best practices we recommend using the from parameter as well to define a specific time frame. When used in conjunction with the from parameter, the value of to will be relative to the value of from, not relative to the current time.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
to=+6hours
to=+5days
to=1302883980
to=MM/DD/YYYY
to=YYYY/MM/DD
to=2017-02-27 5:00 PM
filter filter=:string Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.
radius radius=:distance:unit When requesting the closest results within a circle, the radius determines how far from the specified location to search. A valid unit value must be included in your radius value, e.g., "5mi", "10km", "25miles". If no unit is provided, your value is assumed to be in meters by default.

Most endpoints utilize a default radius of 50 miles, though some endpoints, such as lightning, may have tighter restrictions specified.
minradius minradius=:distance:unit When requesting the closest results within a circle, the minradius determines how far from the specified location to search to begin searching results. A valid unit value must be included in your minimum radius value, e.g., "5mi", "10km", or "25miles". If no unit is provided, your value is assumed to be in meters by default.
When combined with the radius parameter, donut style queries can be made for point data, such as lightning.
format format=:string Defines the API output format. The available options include:
format=json - Standard JSON output. This is the default.
format=geojson - API will output GeoJSON.

If obtaining GeoJSON and using the fields parameter, be sure to include loc to ensure geographical references are available in the response.
mindist mindist=:distance:unit When using the route action, mindist determines the minimum distance along the route to return the requested data for. A valid unit value must be included in your mindist value, e.g. "5mi", "10km", "50miles". If no unit is provided, your value is assumed to be in meters by default.

The default minimum distance between route data is 5 miles if not specified.
limit limit=:total The total number of results to return as an integer. Each endpoint may have a set maximum for this value depending on usage.

The default limit is 1 if not specified. The maximum limit for this endpoint is 250.
query query=:string Used to filter results based on certain fields in the data set. See Advanced Queries for more details.
skip skip=:number Used to skip over a specific number of results in the data set.
sort sort=:string Used to sort results based on certain fields in the data set. See Sorting for more details.
plimit plimit=:total Applied only on the periods property, the total number of periods to return as an integer. The maximum plimit for this endpoint is 250.
pskip pskip=:number Applied only on the periods property, used to skip over a specific number of periods in the data set.

Supported Filters

The following filters can be passed to the filter parameter to reduce the results that are returned:

severe Limit to lightning storm threats that are flagged as severe
notsevere Limit to lightning storm threats that are flagged as not severe
forceutc Force all ISO dates in the API output to use UTC vs. the localized timezone

Supported Query Properties

Use the following supported property keys when creating custom queries for your requests:

stormid Query by Lightning Storm threat ID
issued Query by the issued date/time
minvalidtime Query by the minimum forecast period date/time for the lightning storm threat
maxvalidtime Query by the maximum forecast period date/time for the lightning storm threat. Each lightning storm threat may have up to a 60 minute forecast period.
speed Query by the estimated speed in knots of the lightning storm threat
added Query by the date/time the lightning threat become available within the API
created An alias for added

Sortable Fields

You can use the following fields to sort data. Review the sorting docs page for more information on the sort functionality.

stormid Sort by the Lightning storm threat ID
minvalidtime Sort by the minimum valid date/time of the threat
maxvalidtime Sort by the maximum valid date/time of the threat

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Default
GeoJSON

{
    "id": "111523041",
    "dataSource": "vaisala-lightning",
    "details": {
      "stormId": "111523041",
      "issuedTimestamp": 1667337840,
      "issuedDateTimeISO": "2022-11-01T21:24:00+00:00",
      "range": {
        "minTimestamp": 1667337840,
        "minDateTimeISO": "2022-11-01T21:24:00+00:00",
        "maxTimestamp": 1667338440,
        "maxDateTimeISO": "2022-11-01T21:34:00+00:00"
      },
      "severe": false,
      "movement": {
        "dirDEG": 154,
        "dir": "SSE",
        "speedKTS": 13.3,
        "speedKMH": 24.63,
        "speedKPH": 24.63,
        "speedMPH": 15.31,
        "reliability": "LOW"
      },
      "totalPeriods": 1
    },
    "periods": [
      {
        "id": "111523041-1667338440",
        "range": {
          "minTimestamp": 1667337840,
          "minDateTimeISO": "2022-11-01T21:24:00+00:00",
          "maxTimestamp": 1667338440,
          "maxDateTimeISO": "2022-11-01T21:34:00+00:00"
        },
        "centroid": {
          "type": "Point",
          "coordinates": [
            22.81321,
            -25.50493
          ]
        },
        "polygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                22.85785,
                -25.67844
              ],
              [
                22.82298,
                -25.67719
              ],
              [
                22.81005,
                -25.67549
              ],
              [
                22.79802,
                -25.6705
              ],
              [
                22.66986,
                -25.59444
              ],
              [
                22.65953,
                -25.58652
              ],
              [
                22.6516,
                -25.57619
              ],
              [
                22.64662,
                -25.56415
              ],
              [
                22.64492,
                -25.55124
              ],
              [
                22.64662,
                -25.53833
              ],
              [
                22.6516,
                -25.5263
              ],
              [
                22.68732,
                -25.47301
              ],
              [
                22.69525,
                -25.46268
              ],
              [
                22.73735,
                -25.41774
              ],
              [
                22.74767,
                -25.40981
              ],
              [
                22.75969,
                -25.40483
              ],
              [
                22.82797,
                -25.39279
              ],
              [
                22.84087,
                -25.39109
              ],
              [
                22.85377,
                -25.39279
              ],
              [
                22.86579,
                -25.39777
              ],
              [
                22.89807,
                -25.4145
              ],
              [
                22.90839,
                -25.42242
              ],
              [
                22.91632,
                -25.43275
              ],
              [
                22.9213,
                -25.44477
              ],
              [
                22.92299,
                -25.45767
              ],
              [
                22.92075,
                -25.58613
              ],
              [
                22.91905,
                -25.59904
              ],
              [
                22.90606,
                -25.64144
              ],
              [
                22.90108,
                -25.65348
              ],
              [
                22.89315,
                -25.66382
              ],
              [
                22.88281,
                -25.67175
              ],
              [
                22.87077,
                -25.67674
              ],
              [
                22.85785,
                -25.67844
              ]
            ]
          ]
        }
      }
    ],
    "forecastPath": {
      "type": "LineString",
      "coordinates": [
        [
          22.83126,
          -25.53819
        ],
        [
          22.7231,
          -25.33861
        ]
      ]
    },
    "profile": {
      "tz": "UTC"
    }
  }

								

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "111523041-1667339280-polygon",
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              22.81507,
              -25.58328
            ],
            [
              22.80216,
              -25.58158
            ],
            [
              22.79013,
              -25.5766
            ],
            [
              22.73973,
              -25.54648
            ],
            [
              22.72939,
              -25.53856
            ],
            [
              22.72147,
              -25.52823
            ],
            [
              22.69929,
              -25.49154
            ],
            [
              22.68879,
              -25.46764
            ],
            [
              22.68381,
              -25.45562
            ],
            [
              22.68211,
              -25.44272
            ],
            [
              22.68261,
              -25.43857
            ],
            [
              22.68431,
              -25.42567
            ],
            [
              22.68824,
              -25.40245
            ],
            [
              22.69322,
              -25.39044
            ],
            [
              22.70114,
              -25.38012
            ],
            [
              22.71146,
              -25.37219
            ],
            [
              22.72348,
              -25.36722
            ],
            [
              22.82699,
              -25.32923
            ],
            [
              22.83989,
              -25.32753
            ],
            [
              22.85278,
              -25.32923
            ],
            [
              22.86269,
              -25.33287
            ],
            [
              22.8747,
              -25.33785
            ],
            [
              22.91702,
              -25.36182
            ],
            [
              22.92734,
              -25.36974
            ],
            [
              22.93526,
              -25.38006
            ],
            [
              22.94023,
              -25.39208
            ],
            [
              22.94193,
              -25.40498
            ],
            [
              22.94023,
              -25.41787
            ],
            [
              22.93526,
              -25.42989
            ],
            [
              22.91947,
              -25.45821
            ],
            [
              22.85827,
              -25.55834
            ],
            [
              22.85034,
              -25.56867
            ],
            [
              22.84001,
              -25.5766
            ],
            [
              22.82798,
              -25.58158
            ],
            [
              22.81507,
              -25.58328
            ]
          ]
        ]
      },
      "properties": {
        "featureType": "polygon",
        "period": {
          "range": {
            "minTimestamp": 1667338680,
            "minDateTimeISO": "2022-11-01T21:38:00+00:00",
            "maxTimestamp": 1667339280,
            "maxDateTimeISO": "2022-11-01T21:48:00+00:00"
          }
        },
        "id": "111523041",
        "dataSource": "vaisala-lightning",
        "details": {
          "stormId": "111523041",
          "issuedTimestamp": 1667338680,
          "issuedDateTimeISO": "2022-11-01T21:38:00+00:00",
          "range": {
            "minTimestamp": 1667338680,
            "minDateTimeISO": "2022-11-01T21:38:00+00:00",
            "maxTimestamp": 1667339280,
            "maxDateTimeISO": "2022-11-01T21:48:00+00:00"
          },
          "severe": false,
          "movement": {
            "dirDEG": 164,
            "dir": "SSE",
            "speedKTS": 18.07,
            "speedKMH": 33.46,
            "speedKPH": 33.46,
            "speedMPH": 20.79,
            "reliability": "LOW"
          },
          "totalPeriods": 1
        },
        "profile": {
          "tz": "UTC"
        }
      }
    },
    {
      "id": "111523041-1667339280-centroid",
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          22.81778,
          -25.42672
        ]
      },
      "properties": {
        "featureType": "centroid",
        "period": {
          "range": {
            "minTimestamp": 1667338680,
            "minDateTimeISO": "2022-11-01T21:38:00+00:00",
            "maxTimestamp": 1667339280,
            "maxDateTimeISO": "2022-11-01T21:48:00+00:00"
          }
        },
        "id": "111523041",
        "dataSource": "vaisala-lightning",
        "details": {
          "stormId": "111523041",
          "issuedTimestamp": 1667338680,
          "issuedDateTimeISO": "2022-11-01T21:38:00+00:00",
          "range": {
            "minTimestamp": 1667338680,
            "minDateTimeISO": "2022-11-01T21:38:00+00:00",
            "maxTimestamp": 1667339280,
            "maxDateTimeISO": "2022-11-01T21:48:00+00:00"
          },
          "severe": false,
          "movement": {
            "dirDEG": 164,
            "dir": "SSE",
            "speedKTS": 18.07,
            "speedKMH": 33.46,
            "speedKPH": 33.46,
            "speedMPH": 20.79,
            "reliability": "LOW"
          },
          "totalPeriods": 1
        },
        "profile": {
          "tz": "UTC"
        }
      }
    },
    {
      "id": "111523041-forecastPath",
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            22.83316,
            -25.47509
          ],
          [
            22.74105,
            -25.18484
          ]
        ]
      },
      "properties": {
        "featureType": "forecastPath",
        "id": "111523041",
        "dataSource": "vaisala-lightning",
        "details": {
          "stormId": "111523041",
          "issuedTimestamp": 1667338680,
          "issuedDateTimeISO": "2022-11-01T21:38:00+00:00",
          "range": {
            "minTimestamp": 1667338680,
            "minDateTimeISO": "2022-11-01T21:38:00+00:00",
            "maxTimestamp": 1667339280,
            "maxDateTimeISO": "2022-11-01T21:48:00+00:00"
          },
          "severe": false,
          "movement": {
            "dirDEG": 164,
            "dir": "SSE",
            "speedKTS": 18.07,
            "speedKMH": 33.46,
            "speedKPH": 33.46,
            "speedMPH": 20.79,
            "reliability": "LOW"
          },
          "totalPeriods": 1
        },
        "profile": {
          "tz": "UTC"
        }
      }
    }
  ]
}

Response Properties

The following properties will be provided in every response object:

id (string) The Lightning Storm Threat ID
dataSource (string) The lightning threats data source. Supported sources:
- vaisala-lightning
details (object) Lightning storm threat details object
details.stormId (string) The Lightning Storm Threat ID
details.issuedTimestamp (number) The unix timestamp of date/time the lightning storm threat was issued
details.issuedDateTimeISO (number) The ISO8601 date/time the lightning storm threat was issued
details.range (object) The time range object for the storm threat
details.range.minTimestamp (number) The unix timestamp representing the start date/time of the lightning threat
details.range.minDateTimeISO (string) The ISO8601 date representing the start date/time of the lightning threat
details.range.maxTimestamp (number) The unix timestamp representing the ending date/time of the lightning threat
details.range.maxDateTimeISO (string) The ISO8601 date representing the ending date/time of the lightning threat
details.severe (boolean) Flag indicating if this is a severe lightning threat
details.movement (object) The movement object. Null if direction or speed are unavailable.
details.movement.dirDeg (number) The estimated direction of the lightning storm threat in degrees. 0 - 359, with 0 = North,
details.movement.dir (number) The estimated direction of the lightning storm threat is in degrees.

Possible values:
- N - North
- NNE - North northeast
- NE - Northeast
- ENE - East northeast
- E - East
- ESE - East southeast
- SE - Southeast
- SSE - South southeast
- S - South
- SSW - South southwest
- SW - Southwest
- WSW - West southwest
- W - West
- WNW - West northwest
- NW - Northwest
- NNW - North northwest
details.movement.speedKTS (number) The estimated speed of the threat in knots.
details.movement.speedKPH (number) The estimated speed of the threat in kilometers per hour.
details.movement.speedMPH (number) The estimated speed of the threat in miles per hour.
details.movement.reliability (number) The reliability of the estimated threat movement information:

- NOT_AVAILABLE: Not enough history available to estimate motion
- UNPHYSICAL: Estimated storm motion exceeds 120 km/h
- LOW: The default assumption once any given storm has enough history of initializing its motion estimate.
- MEDIUM: LOW reliability can be promoted to MEDIUM or HIGH once there is enough consistency between recent storm motion estimates.
- HIGH: LOW reliability can be promoted to MEDIUM or HIGH once there is enough consistency between recent storm motion estimates.
totalPeriods (number) The total number of 10 minute threat periods associated with the storm
periods (array) An array of the 10 minute threat forecast periods
periods.#.id (string) The ID string for the 10 minute threat forecast period
periods.#.range (array) The time range object for the storm threat period
periods.#.range.minTimestamp (number) The unix timestamp representing the start date/time of the threat period
periods.#.range.minDateTimeISO (string) The ISO8601 date representing the start date/time of the threat period
periods.#.range.maxTimestamp (number) The unix timestamp representing the ending date/time of the threat period
periods.#.range.maxDateTimeISO (string) The ISO8601 date representing the ending date/time of the threat period
periods.#.polygon (object) A GeoJSON polygon object representing the threat coverage area for the period
periods.#.centroid (object) A GeoJSON point object representing the centroid of the coverage area polygon for the period
forecastPath (object) A GeoJSON line string representing the estimated direction of the storm. Null if not available.
profile.tz (string) Timezone name of the location.
profile.tzname (string) The timezone abbreviation for the location.
profile.tzoffset (number) The timezone offset for the location in seconds.
profile.isDST (boolean) True if the location is currently observing Daylight Savings Time (DST), otherwise false.

Last modified: September 08, 2023