Lightning Analytics

Lightning Analytics

URL Path
https://data.api.xweather.com/lightning/analytics/
Data Coverage
Global
Update Interval
Real-time
Time Range
2016 to now
Access Multiplier
12x

Lightning analytics extends the lightning endpoint with additional data points for a robust analysis. Damage potential can now be assessed for each lightning strike, providing insight into the likelihood of metal and non-metal damage. Additionally, each strike will include an error ellipse and details for plotting the ellipse.

The standard lightning/analytics API endpoint access has the following limitations:

  • The maximum radius value is 100km (~62 miles).

  • Lightning data is available for the past 5 minutes.

  • A single query can retrieve up to 1000 lightning strikes. Please note that using the skip parameter will pull the next 1000 strikes.

  • The within and closest actions are unavailable with the standard lightning API endpoint access.

The Lightning Enterprise add-on expands the lightning endpoint capabilities to include the following features:

  • Can perform within queries, allowing queries by polygon and bounding box (rectangle) for client-defined areas.

  • Can perform within and closest queries for circles with a maximum radius of 500km (~311 miles).

  • Request up to 24 hours of data per API query.

  • Access to archive lightning data from 2016 to the present day.

  • A single query can retrieve up to 50000 lightning strikes. Please note that using the skip parameter will pull the next 50000 strikes.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/lightning/analytics/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

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

ActionDescription
:idType: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
closestType: stringBased on a location search, the results will be returned in order from closest to farthest. Learn more.
routeType: stringAllows you to pass several coordinates along a custom route to return data points at each location. Learn more.
withinType: stringUses a circle or polygon, define an area to search for results. Learn more.

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.

Properties

id (string)

The unique identifier for the lightning record.

loc (object)

The location of the record.

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

ob (object)

Object containing the lightning observation.

ob.timestamp (number)

Unix timestamp of the lightning pulse.

ob.dateTimeISO (string)

ISO 8601 date of the lightning pulse.

ob.timestampMS (number)

Unix timestamp of the lightning pulse in milliseconds.

ob.dateTimeISOMS (string)

ISO 8601 date of the lightning pulse in milliseconds.

ob.age (number)

Seconds since the lightning pulse.

ob.pulse (object)

Object containing the lightning pulse information.

ob.pulse.type (string)

One of the two types of lightning pulses.
- IC: Intracloud
- CG: Cloud-to-ground (Strike)

ob.pulse.peakamp (number)

The peak amplitude of the lightning pulse. Polarity is determined by a negative or positive value.

ob.pulse.peakAmp (number)

DEPRECATED Use `ob.pulse.peakamp` instead.

ob.pulse.numSensors (number)

The number of sensors that detected the lightning pulse.

ob.pulse.icHeightM (number)

Deprecated

ob.pulse.icHeightFT (number)

Deprecated

recTimestamp (number)

The Unix timestamp of the time the lightning strike information was received.

recISO (string)

The ISO 8601 date of the time the lightning strike information was received.

age (number)

DEPRECATED Use `ob.age` instead.

damagePotential (object)

Object containing the damage potential properties.

damagePotential.continuingCurrentProbability (string)

Enum representing the textual probability of the strike containing a long continuing current. Null if unavailable. [`LOWEST`, `LOW`, `MEDIUM`, `HIGH` `HIGHEST`]

damagePotential.metalDamagePotential (number)

Percentile of the accumulated metallic heating potential from impulse charge to the strike point.

damagePotential.nonMetalDamagePotential (number)

Percentile of the accumulated non-metallic heating potential from impulse charge to the strike point.

damagePotential.impulseChargeC (number)

Estimated accumulated impulse charge for the strike, most relevant for metal objects in Coulombs.

damagePotential.impulseSpecificEnergyJPO (number)

Estimated accumulated impulse specific energy for the strike, most relevant for non-metal objects in Joules/Ohm.

damagePotential.strokeCount (number)

Strokes in strike.

ellipse (object)

Object containing the confidence ellipse properties.

ellipse.polygon (object)

GeoJSON object containing confidence ellipse plotting properties.

ellipse.angleDegree (number)

Semi-major axis angle in degrees East of North.

ellipse.polygon.type (string)

Type of GeoJson geometry

ellipse.polygon.coordinates (array)

List of coordinates that generate the GeoJson geometry

ellipse.semiMajorM (number)

Semi-major axis in meters.

ellipse.semiMajorFT (number)

Semi-major axis in feet.

ellipse.semiMinorM (number)

Semi-minor axis in meters.

ellipse.semiMinorFT (number)

Semi-minor axis in feet.

relativeTo (object)

Object containing information about the location used for the request compared to the record"s actual location.

relativeTo.lat (number)

Latitude coordinate of the location used for the request. This may be different than the record"s loc.lat value if there was no record exactly at the request location.

relativeTo.long (number)

Longitude coordinate of the location used for the request. This may be different than the record"s loc.long value if there was no record exactly at the request location.

relativeTo.bearing (number)

Bearing in degrees of the record"s location relative to the location used for the request.

relativeTo.bearingENG (string)

Cardinal direction of the record relative to the location used for the request.

relativeTo.distanceKM (number)

Distance, in kilometers, from the requested location to the record"s actual location.

relativeTo.distanceMI (number)

Distance, in miles, from the requested location to the record"s actual location.

[
  {
    "id": "vd80585829e3c45066fcfd7033d1bda40",
    "loc": {
      "long": 37.5629,
      "lat": 14.4987
    },
    "ob": {
      "timestamp": 1718037532,
      "dateTimeISO": "2024-06-10T16:38:52+00:00",
      "timestampMS": 1718037532879,
      "dateTimeISOMS": "2024-06-10T16:38:52.879+00:00",
      "age": 300,
      "pulse": {
        "type": "cg",
        "peakamp": -10600,
        "peakAmp": -10600,
        "numSensors": 5,
        "icHeightFT": 0,
        "icHeightM": 0
      }
    },
    "recTimestamp": 1718037532,
    "recISO": "2024-06-10T16:38:52+00:00",
    "age": 300,
    "damagePotential": {
      "continuingCurrentProbability": "LOWER",
      "metalDamagePotential": 1,
      "nonMetalDamagePotential": 2,
      "impulseChargeC": 1,
      "impulseSpecificEnergyJPO": 5242,
      "strokeCount": 1
    },
    "ellipse": {
      "polygon": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                37.59230804,
                14.47631264
              ],
              [
                37.59126663,
                14.48291779
              ],
              [
                37.58262634,
                14.49375534
              ],
              [
                37.56868362,
                14.5059166
              ],
              [
                37.55321503,
                14.51613331
              ],
              [
                37.54032898,
                14.52168941
              ],
              [
                37.53348923,
                14.52108479
              ],
              [
                37.53452682,
                14.51447964
              ],
              [
                37.54317093,
                14.50364399
              ],
              [
                37.55711365,
                14.49148464
              ],
              [
                37.57258606,
                14.48126698
              ],
              [
                37.58546448,
                14.47570801
              ],
              [
                37.59230804,
                14.47631264
              ]
            ]
          ]
        ]
      },
      "angleDegree": 128,
      "semiMajorM": 4025,
      "semiMinorM": 1014,
      "semiMajorFT": 13205,
      "semiMinorFT": 3327
    },
    "relativeTo": {
      "lat": 14.41,
      "long": 37.69,
      "bearing": 306,
      "bearingENG": "NW",
      "distanceKM": 16.869,
      "distanceMI": 10.482
    }
  }
]