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.
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. |
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 rangeSupports 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. |
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 |
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 |
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 |
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.
{
"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"
}
}
}
]
}
The following properties will be provided in every response object:
Last modified: September 08, 2023