Global Lightning API

Lightning API

4.0.0

OAS3

Lightning Data REST API

Response Content-Types header

The binary/octet-stream response content type is GeoJSON data encoded into protocol buffers (geobuf). Decoded, the data is the same as the JSON/GeoJSON content types (in particular, it is a lossless compression). Where available, we recommend that you accept protocol buffer output for your application if you have been previously using GeoJSON responses, because it typically makes responses 6–8 times smaller (2–2.5 times smaller with gzip compression, which is also enabled by default for sufficiently large queries), and because it allows for fast, incremental parsing.

There is also a vector tile endpoint that serves protocol buffers, but these are explicitly in the Mapbox Vector Tile specification. That is to say, they do not decode into GeoJSON, and that this encoding is lossy, due to projection transformation and quantization onto a 4096x4096 coordinate space.

Response Cache-Control header

Note that if you ask the API for a response that is "closed" (such as a defined time range in the past), then the server will respond with an aggressive Cache-Control such as public, max-age=31536000. This is because large queries are expensive to run, and very unlikely to change.

However if you make an open-ended query, or use a time parameter that closes in the future, then the Cache-Control expires much sooner: currently after 60 seconds. Note that due to latency from source to service, there is a five-minute grace period in which any data contained in the underlying database is not considered "complete" and a re-request is advised through the Cache-Control header.

This applies to all /strikes endpoints. This is particularly useful for ensuring that Mapbox GL maps will use vector tiles dynamically, since the Cache-Control header is respected in Mapbox GL Native and in Mapbox GL JS.

Lightning Data WebSockets

This service supports providing data by WebSockets but unfortunately Open-API specs don't have WebSocket support so this is the extent of the documentation for it. NOTE: This service differs greatly from v2/3 of the API

Establishing a connection and getting data

When you first establish a connection to wss://${hostDomain}/v4?token=${jwt} you will only receive heartbeats. The service will wait for you to specify what data you are interested in. You do so by sending it a message like so:

  {

    "action": "SET\_PREFERENCES"
    "bbox": [-180, -90, 180, 90],
    "providers": ["TOA", "MOCK"],
    "directions": ["CLOUD"],
    "pathToGenerateAlong": [[-180,-90],[-90,-45],[0,0]],
    "format": "application/vnd.google-earth.kml+xml"

  }

It will either respond with an error:

  {
    "type": "SET\_PREFERENCES\_ERROR"
    "error": "Error parsing 'bbox': MinLon/minLat cannot be higher that maxLon/maxLat"
  }

Or it will send a succesful response like so:

  {
    "type": "PREFERENCES\_APPLIED",
    "preferences": {
      "bbox": [-180, -90, 180, 90],
      "providers": ["TOA", "MOCK"],
      "directions": ["CLOUD"],
      "pathToGenerateAlong": [[-180,-90],[-90,-45],[0,0]],
      "fromTime": "2019-10-12T00:00:00.000Z",
      "format": "application/vnd.google-earth.kml+xml",
      "limit": 10000
  }

NOTE: fromTime and limit are included because they may be returned. However they are used for getting historical data over WebSockets, and this functionality is not live at launch. When this is functional, it will then return any strikes since the fromTime (so long as that was within 3 hours ago), and it formats those strikes as requested. After the preferences applied message, you will immediately receive any real-time strikes, so depending on how long the historical strikes query takes you may receive real-time data before receiving the historical data.

Disconnections The WebSockets will reset every 2 hours, this is controlled by AWS and cannot be changed. We suggest that you open a second socket when the first is due to reset to ensure there are no missed strikes.

We have added the ability to get historical data over WebSockets to limit the annoyance this may cause, but this functionality will not be live at launch. You can of course use the REST API to fill in any missing data if you would prefer.

When lightning data is received

When lightning is received it is immediately sent, however we reserve the right to aggreggate multiple strikes into a single message in the future. To this end, it sends the equivalent of a collection of strikes even if an individual strike is sent, so for KML you will get a complete XML document that may only contain one Placemark. It is up to the client to handle merging that into any data they may already have.

  {
    "type": "LIGHTNING\_STRIKES\_RECEIVED",
    "lightningStrikes": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>Lightning StrikeTime:2019-11-05T11:22:34.000Z, Current:-22.3kA, Type:GROUND2019-11-05T11:22:34.000Z321.2-22.3GROUND2.3toaLightning StrikeTime:2019-11-05T11:22:34.000Z, Current:-22.3kA, Type:GROUND-130,25"
  }

Data from toa or transpower are sent as soon as we receive it, but they are not guarenteed to be in order as there may be propogation delays further upstream and strikes may be delayed by up to 5 minutes. Mock strikes are generated and sent every minute.

Heartbeats

The service will send a heartbeat every 2 minutes to tell you the service and connection is still alive

  {
    "type": "HEARTBEAT",
    "rate": "cron(0/2 _ _ _ ? _)"
  }

You may test this earlier by sending an ECHO message:

ECHO

  {
    "action": "ECHO",
    "payload": "Are you there?"
  }

The service will respond with the payload of the message back.

  {
    "type": "ECHO",
    "payload": "Are you there?"
  }