Documentation

Weather Alerts & Advanced Features

Stay ahead of severe weather with real-time alerts, visual radar imagery, and satellite data. Our advanced monitoring systems provide critical weather warnings and comprehensive visualization tools.

Weather Alerts & Warnings

Get Active Weather Alerts

Retrieve current weather alerts and warnings for any location, including severe weather watches, warnings, and advisories.

Endpoint: GET /weather/alerts

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`severity`	string	No	Filter by severity: `minor`, `moderate`, `severe`, `extreme`

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/alerts?lat=32.7767&lon=-96.7970&severity=severe" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 32.7767,
    "lon": -96.797,
    "name": "Dallas",
    "country": "United States",
    "region": "Texas",
    "timezone": "America/Chicago"
  },
  "alerts": [
    {
      "id": "ALERT-2024-TX-001",
      "title": "Severe Thunderstorm Warning",
      "description": "A severe thunderstorm is expected to affect the Dallas metropolitan area with heavy rain, strong winds up to 70 mph, and possible hail up to quarter size. Take immediate shelter in a sturdy building.",
      "severity": "severe",
      "urgency": "immediate",
      "certainty": "likely",
      "event": "thunderstorm",
      "start_time": "2024-01-15T22:00:00Z",
      "end_time": "2024-01-16T02:00:00Z",
      "areas": ["Dallas County", "Collin County", "Denton County"]
    },
    {
      "id": "ALERT-2024-TX-002",
      "title": "Flash Flood Watch",
      "description": "Heavy rainfall may cause flash flooding in low-lying and poor drainage areas. Do not drive through flooded roadways.",
      "severity": "moderate",
      "urgency": "expected",
      "certainty": "possible",
      "event": "flood",
      "start_time": "2024-01-15T20:00:00Z",
      "end_time": "2024-01-16T06:00:00Z",
      "areas": ["Dallas-Fort Worth Metroplex"]
    }
  ],
  "count": 2
}

Alert Severity Levels

Severity	Description	Response Action
Minor	Limited threat to life/property	Monitor conditions
Moderate	Possible threat to life/property	Prepare for action
Severe	Significant threat to life/property	Take protective action
Extreme	Extraordinary threat	Take immediate action

Alert Types

Our system monitors and issues alerts for:

Thunderstorms: Severe storms with damaging winds, hail, or tornadoes
Tornadoes: Tornado watches and warnings
Floods: Flash floods, river flooding, coastal flooding
Hurricanes: Tropical cyclones and hurricanes
Winter Weather: Snow storms, ice storms, blizzards
Extreme Temperatures: Heat waves, extreme cold
High Winds: Damaging wind events
Fog: Dense fog affecting visibility

Alert Subscriptions

Create automated alert subscriptions to receive notifications via email, webhook, or SMS when severe weather threatens your specified locations.

Endpoint: POST /weather/alerts/subscribe

Request Body

Code(json)
 
{
  "locations": [
    {
      "lat": 40.7128,
      "lon": -74.006,
      "radius": 25.0
    }
  ],
  "alert_types": ["thunderstorm", "tornado", "flood", "hurricane"],
  "severity_levels": ["severe", "extreme"],
  "notification_method": {
    "email": "[email protected]",
    "webhook": "https://example.com/weather-alerts",
    "sms": "+1-555-123-4567"
  },
  "active": true
}

Example Request

Code(bash)
 
curl -X POST "https://api.supaweather.com/v2/weather/alerts/subscribe" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {
        "lat": 37.7749,
        "lon": -122.4194,
        "radius": 50.0
      }
    ],
    "alert_types": ["earthquake", "tsunami", "flood"],
    "severity_levels": ["severe", "extreme"],
    "notification_method": {
      "email": "[email protected]",
      "webhook": "https://api.mycompany.com/weather-webhook"
    }
  }'

Example Response

Code(json)
 
{
  "subscription_id": "sub_2024_001_abc123",
  "status": "active",
  "created_at": "2024-01-15T14:30:00Z",
  "locations": [
    {
      "lat": 37.7749,
      "lon": -122.4194,
      "radius": 50.0
    }
  ],
  "alert_types": ["earthquake", "tsunami", "flood"],
  "notification_method": {
    "email": "[email protected]",
    "webhook": "https://api.mycompany.com/weather-webhook"
  }
}

Webhook Payload Format

When alerts are triggered, webhooks receive this payload:

Code(json)
 
{
  "subscription_id": "sub_2024_001_abc123",
  "timestamp": "2024-01-15T22:15:00Z",
  "alert": {
    "id": "ALERT-2024-CA-001",
    "title": "Earthquake Warning",
    "severity": "extreme",
    "event": "earthquake",
    "location": {
      "lat": 37.7749,
      "lon": -122.4194,
      "name": "San Francisco"
    },
    "start_time": "2024-01-15T22:15:00Z",
    "end_time": "2024-01-15T22:30:00Z",
    "description": "A magnitude 6.5 earthquake has been detected. Seek immediate shelter and drop, cover, and hold on."
  }
}

Radar & Satellite Imagery

Weather Radar

Access real-time weather radar imagery showing precipitation, storm movement, and intensity.

Endpoint: GET /weather/radar

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`zoom`	integer	No	Zoom level (1-10, default: 5)
`layer`	string	No	Radar layer: `precipitation`, `clouds`, `temperature`, `wind`

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/radar?lat=39.7392&lon=-104.9903&zoom=6&layer=precipitation" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 39.7392,
    "lon": -104.9903,
    "name": "Denver",
    "country": "United States",
    "region": "Colorado",
    "timezone": "America/Denver"
  },
  "radar": {
    "image_url": "https://radar-images.supaweather.com/precipitation/denver-20240115-1830.png",
    "layer": "precipitation",
    "timestamp": "2024-01-15T18:30:00Z",
    "zoom_level": 6
  }
}

Satellite Imagery

Access high-resolution satellite images showing cloud cover, atmospheric conditions, and weather patterns.

Endpoint: GET /weather/maps/satellite

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`layer`	string	No	Imagery layer: `visible`, `infrared`, `water_vapor`, `enhanced`
`zoom`	integer	No	Zoom level (1-10, default: 5)
`timestamp`	string	No	Specific image timestamp (ISO 8601)

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/maps/satellite?lat=25.7617&lon=-80.1918&layer=infrared&zoom=7" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 25.7617,
    "lon": -80.1918,
    "name": "Miami",
    "country": "United States",
    "region": "Florida",
    "timezone": "America/New_York"
  },
  "satellite": {
    "image_url": "https://satellite-images.supaweather.com/infrared/miami-20240115-1845.jpg",
    "layer": "infrared",
    "satellite_name": "GOES-16",
    "timestamp": "2024-01-15T18:45:00Z",
    "zoom_level": 7,
    "resolution": {
      "width": 1024,
      "height": 1024,
      "meters_per_pixel": 500.0
    },
    "bbox": {
      "north": 26.2617,
      "south": 25.2617,
      "east": -79.6918,
      "west": -80.6918
    }
  }
}

Satellite Layer Types

Layer	Description	Best For
Visible	Natural color imagery	Daytime cloud observation
Infrared	Temperature-based imagery	24/7 cloud detection, storm analysis
Water Vapor	Atmospheric moisture	Upper-level wind patterns, jet streams
Enhanced	Color-enhanced infrared	Storm intensity, precipitation analysis

Implementation Examples

Real-time Alert Monitoring

Code(javascript)
 
class WeatherAlertMonitor {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = "https://api.supaweather.com/v2";
    this.subscriptions = new Map();
  }

  async checkAlerts(lat, lon, severityFilter = null) {
    const params = new URLSearchParams({
      lat: lat.toString(),
      lon: lon.toString(),
    });

    if (severityFilter) {
      params.append("severity", severityFilter);
    }

    const response = await fetch(`${this.baseURL}/weather/alerts?${params}`, {
      headers: { "X-API-Key": this.apiKey },
    });

    if (!response.ok) {
      throw new Error(`Alert check failed: ${response.statusText}`);
    }

    return response.json();
  }

  async subscribeToAlerts(config) {
    const response = await fetch(`${this.baseURL}/weather/alerts/subscribe`, {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(config),
    });

    if (!response.ok) {
      throw new Error(`Subscription failed: ${response.statusText}`);
    }

    const subscription = await response.json();
    this.subscriptions.set(subscription.subscription_id, subscription);
    return subscription;
  }

  // Poll for alerts every 5 minutes
  startMonitoring(lat, lon, callback) {
    const monitor = setInterval(
      async () => {
        try {
          const alerts = await this.checkAlerts(lat, lon, "severe");
          if (alerts.count > 0) {
            callback(alerts);
          }
        } catch (error) {
          console.error("Alert monitoring error:", error);
        }
      },
      5 * 60 * 1000,
    ); // 5 minutes

    return monitor;
  }
}

// Usage
const alertMonitor = new WeatherAlertMonitor("your-api-key");

// Set up monitoring for Dallas
alertMonitor.startMonitoring(32.7767, -96.797, (alerts) => {
  console.log(`⚠️ ${alerts.count} severe weather alert(s) for Dallas:`);
  alerts.alerts.forEach((alert) => {
    console.log(`- ${alert.title} (${alert.severity})`);
    console.log(`  ${alert.description}`);
  });
});

Radar Image Integration

Code(python)
 
import requests
import io
from PIL import Image
import matplotlib.pyplot as plt

class RadarImagery:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.supaweather.com/v2"

    def get_radar_image(self, lat, lon, layer='precipitation', zoom=5):
        """Fetch and display radar imagery."""
        url = f"{this.base_url}/weather/radar"
        params = {
            'lat': lat,
            'lon': lon,
            'layer': layer,
            'zoom': zoom
        }
        headers = {'X-API-Key': this.api_key}

        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()

        radar_data = response.json()
        return radar_data

    def download_and_display_radar(self, lat, lon, layer='precipitation'):
        """Download and display radar image."""
        radar_data = self.get_radar_image(lat, lon, layer)
        image_url = radar_data['radar']['image_url']

        # Download the image
        img_response = requests.get(image_url)
        img_response.raise_for_status()

        # Open and display the image
        image = Image.open(io.BytesIO(img_response.content))

        plt.figure(figsize=(10, 8))
        plt.imshow(image)
        plt.title(f"Weather Radar - {radar_data['location']['name']}")
        plt.subtitle(f"Layer: {layer.title()} | {radar_data['radar']['timestamp']}")
        plt.axis('off')
        plt.show()

        return image

# Usage
radar = RadarImagery('your-api-key')

# Display precipitation radar for Chicago
radar.download_and_display_radar(41.8781, -87.6298, 'precipitation')

Alert Webhook Server

Code(python)
 
from flask import Flask, request, jsonify
import json
from datetime import datetime

app = Flask(__name__)

# Store for received alerts
alert_store = []

@app.route('/weather-webhook', methods=['POST'])
def handle_weather_alert():
    """Handle incoming weather alert webhooks."""
    try:
        alert_data = request.json

        # Validate webhook payload
        required_fields = ['subscription_id', 'timestamp', 'alert']
        if not all(field in alert_data for field in required_fields):
            return jsonify({'error': 'Invalid payload'}), 400

        # Store the alert
        alert_store.append({
            'received_at': datetime.utcnow().isoformat(),
            'data': alert_data
        })

        # Process the alert
        alert = alert_data['alert']
        location = alert['location']['name']
        severity = alert['severity']
        title = alert['title']

        print(f"🚨 ALERT RECEIVED: {title}")
        print(f"📍 Location: {location}")
        print(f"⚠️ Severity: {severity.upper()}")
        print(f"📝 Description: {alert['description']}")
        print("-" * 50)

        # Here you could:
        # - Send notifications to your team
        # - Update your application's alert status
        # - Trigger automated responses
        # - Log to monitoring systems

        # Send to notification service
        send_notification(alert)

        return jsonify({'status': 'success', 'received': True}), 200

    except Exception as e:
        print(f"Error processing alert: {e}")
        return jsonify({'error': 'Processing failed'}), 500

def send_notification(alert):
    """Send alert notification to your preferred service."""
    # Example: Send to Slack, Discord, email, SMS, etc.
    notification_text = f"""
    🚨 WEATHER ALERT

    {alert['title']}
    Location: {alert['location']['name']}
    Severity: {alert['severity'].upper()}

    {alert['description']}

    Valid: {alert['start_time']} - {alert['end_time']}
    """

    # Implement your notification logic here
    print("📱 Notification sent!")

@app.route('/alerts', methods=['GET'])
def get_stored_alerts():
    """Retrieve stored alerts."""
    return jsonify({
        'alerts': alert_store,
        'count': len(alert_store)
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

Multi-Location Alert Dashboard

Code(php)
 
<?php
class WeatherAlertDashboard {
    private $apiKey;
    private $locations;
    private $baseUrl = 'https://api.supaweather.com/v2';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
        $this->locations = [
            'New York' => ['lat' => 40.7128, 'lon' => -74.006],
            'Los Angeles' => ['lat' => 34.0522, 'lon' => -118.2437],
            'Chicago' => ['lat' => 41.8781, 'lon' => -87.6298],
            'Houston' => ['lat' => 29.7604, 'lon' => -95.3698],
            'Miami' => ['lat' => 25.7617, 'lon' => -80.1918]
        ];
    }

    public function checkAllLocations() {
        $alerts = [];

        foreach ($this->locations as $city => $coords) {
            $cityAlerts = $this->getAlertsForLocation($coords['lat'], $coords['lon']);
            if ($cityAlerts && $cityAlerts['count'] > 0) {
                $alerts[$city] = $cityAlerts;
            }
        }

        return $alerts;
    }

    private function getAlertsForLocation($lat, $lon) {
        $url = $this->baseUrl . '/weather/alerts';
        $params = http_build_query([
            'lat' => $lat,
            'lon' => $lon,
            'severity' => 'severe'
        ]);

        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => 'X-API-Key: ' . $this->apiKey
            ]
        ]);

        $response = file_get_contents($url . '?' . $params, false, $context);
        return json_decode($response, true);
    }

    public function generateAlertReport() {
        $alerts = $this->checkAllLocations();

        if (empty($alerts)) {
            return "✅ No severe weather alerts for monitored locations.";
        }

        $report = "🚨 WEATHER ALERT SUMMARY\n";
        $report .= str_repeat("=", 50) . "\n\n";

        foreach ($alerts as $city => $cityAlerts) {
            $report .= "📍 {$city}: {$cityAlerts['count']} alert(s)\n";

            foreach ($cityAlerts['alerts'] as $alert) {
                $report .= "  ⚠️ {$alert['title']} ({$alert['severity']})\n";
                $report .= "     {$alert['description']}\n";
                $report .= "     Valid: {$alert['start_time']} - {$alert['end_time']}\n\n";
            }
        }

        return $report;
    }
}

// Usage
$dashboard = new WeatherAlertDashboard('your-api-key');
echo $dashboard->generateAlertReport();
?>

Best Practices

Alert Management

Severity Filtering: Only subscribe to relevant severity levels to avoid alert fatigue
Geographic Precision: Use appropriate radius settings for your area of interest
Redundancy: Set up multiple notification methods for critical alerts
Testing: Regularly test your webhook endpoints and notification systems

Performance Optimization

Caching: Cache radar/satellite images for 5-10 minutes to reduce API calls
Batch Processing: Check multiple locations in separate API calls rather than sequentially
Error Handling: Implement robust retry logic for failed requests
Rate Limiting: Respect API rate limits, especially for real-time monitoring

Integration Tips

Webhook Security: Validate webhook payloads and use HTTPS endpoints
Alert Deduplication: Track alert IDs to avoid processing duplicates
Geographic Boundaries: Consider timezone differences for alert timing
User Preferences: Allow users to customize alert types and severity levels

Current Weather - Real-time conditions
Weather Forecasts - Prediction data
Historical Data - Past weather records

Support & Resources

Alert Documentation: Complete reference for all alert types
Image Formats: Radar and satellite image specifications
Webhook Testing: Tools for testing webhook integrations
Status Page: Real-time API status and incident reports

Last modified on July 7, 2025

Current Weather Forecasts Historical Climates

Weather Alerts & Advanced Features

Weather Alerts & Warnings

Get Active Weather Alerts

Parameters

Example Request

Example Response

Alert Severity Levels

Alert Types

Alert Subscriptions

Subscribe to Weather Alerts

Request Body

Example Request

Example Response

Webhook Payload Format

Radar & Satellite Imagery

Weather Radar

Parameters

Example Request

Example Response

Satellite Imagery

Parameters

Example Request

Example Response

Satellite Layer Types

Implementation Examples

Real-time Alert Monitoring

Radar Image Integration

Alert Webhook Server

Multi-Location Alert Dashboard

Best Practices

Alert Management

Performance Optimization

Integration Tips

Related Endpoints

Support & Resources