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.warpulse.com/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 and Atlantic region.

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.warpulse.com/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.warpulse.com/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"
    },
    ...
  ]
}

Rate Limits

Limits apply per API key, not per account. Exceeding the rate limit returns HTTP 429. Per-second rate limits are governed by a fair usage policy and scale with your plan.

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.warpulse.com/v1/flashes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -G \
  -d since_minutes=15