Lightning API · Documentation

API Reference

One endpoint. Pass your API key and get back a JSON array of lightning flashes. Filter by time window and geographic bounding box. No SDK required.

Authentication

All requests must include your API key in the X-API-Key header. Keys are generated from your dashboard and can be rotated at any time. Never expose your key in client-side code, proxy requests through your own backend.

curl "https://api.lightningapi.dev/v1/flashes?since_minutes=15" \
  -H "X-API-Key: YOUR_API_KEY"

Endpoint

Returns an array of lightning flash events matching the given filters.

Query Parameters

All parameters are optional. Without a bounding box, the response covers the full Americas, Atlantic, and Pacific region (including Hawaii and Alaska).

Geographic Filtering

Narrow results to any rectangular region by passing all four bounding box parameters together. All four must be present, a partial set returns a 400 error. Coordinates use decimal degrees (WGS84).

Bounding box format

# Florida
curl "https://api.lightningapi.dev/v1/flashes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -G \
  -d since_minutes=15 \
  -d min_lat=24.52 \
  -d max_lat=31.00 \
  -d min_lon=-87.63 \
  -d max_lon=-80.03

# Custom box, NYC metro area
curl "https://api.lightningapi.dev/v1/flashes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -G \
  -d since_minutes=30 \
  -d min_lat=40.45 \
  -d max_lat=41.15 \
  -d min_lon=-74.30 \
  -d max_lon=-73.65

Response Format

Successful responses return HTTP 200 with a JSON object containing a flashes array. Each flash has four fields.

{
  "flashes": [
    {
      "flash_id": 58097,
      "lat": -5.91299,
      "lon": -77.38203,
      "flash_timestamp_utc": "2026-06-25T21:58:59.348063"
    },
    ...
  ]
}

Plan Limits

Every numeric cap referenced above (since_minutes and limit on /v1/flashes) depends on your plan, shown below. Exceeding the rate limit returns HTTP 429; exceeding the history window or per-call limit with an explicitly-passed value returns HTTP 400.

Monthly calls, history window, and limit per call all apply to your account as a whole — extra API keys don't add quota. Rate limit is the one that's tracked separately per key, so each key gets its own allowance.

"History window" is the maximum value allowed for since_minutes. "Limit / call" is the maximum value allowed for limit (default 2,000, itself capped to your plan's value if you don't pass one explicitly). Both silently clamp down to your plan's cap if you never touch the parameter at all; passing a value that explicitly exceeds your plan's cap returns a 400 with a message naming the exact limit.

Monthly quotas reset on your billing anniversary each month, not the calendar month. Usage is visible on your dashboard.

Quota is consumed based on how many flashes a request returns, not per request: every 100 flashes returned costs 1 unit of your monthly quota, with a minimum of 1 unit per call. A request returning 50 flashes still costs 1 unit; a request returning 5,000 flashes costs 50. The X-Quota-Cost response header on every /v1/flashes call tells you exactly what that call cost.

Error Codes

curl "https://api.lightningapi.dev/v1/flashes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -G \
  -d since_minutes=15

Storm Proximity Alerts (Zones & Webhooks)

Define a zone (a center point and a radius) and get a signed webhook POST when a strike lands inside it. Delivery is near real-time and doesn't count against your monthly call quota. Manage zones via the API below, or from the dashboard, using the same X-API-Key header as /v1/flashes for API access. Zone count is capped by plan; see Max zones in the Plan Limits table above.

Endpoints

Request body (POST /developer/zones)

Create a zone

curl -X POST https://api.lightningapi.dev/developer/zones \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Construction Site A",
    "center_lat": 33.41,
    "center_lon": -94.02,
    "radius_km": 10,
    "cooldown_minutes": 5,
    "webhook_url": "https://your-server.example.com/lightning-webhook"
  }'

Debounce & cooldown

The first strike inside a zone fires immediately. Further strikes in that same zone are suppressed for cooldown_minutes (default 5) before it can fire again.

Webhook payload & signature verification

Every delivery includes an X-Lightning-Signature header: sha256=<hex hmac>, computed over the raw request body using your zone's webhook_secret as the HMAC key. Verify it before trusting the payload.

{
  "delivery_id": 4821,
  "zone_id": 123,
  "zone_name": "Construction Site A",
  "flash": { "lat": 33.41, "lon": -94.02, "timestamp_utc": "2026-08-04T18:22:10" },
  "distance_km": 3.2
}

import hashlib, hmac

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Retries

Retried on any non-2xx response or timeout. Your endpoint must respond within 5 seconds; anything slower is treated as a timeout and retried on the same schedule. Use delivery_id for idempotency if you receive the same delivery more than once during a retry window.

Delivery history

GET /developer/zones/{id}/alerts returns each firing's delivery_status, one of pending (queued, not yet delivered), delivered (2xx received), or failed (all 4 attempts exhausted). Useful for confirming whether your endpoint is actually receiving deliveries.