SPC Geo

A package for fetching and processing National Weather Service (NWS) alerts and watches with geospatial data support.

Explanation

This package connects to the NWS API to fetch active weather alerts and watches, then processes them to provide:

• Geospatial data: GeoJSON FeatureCollections for mapping
• Zone lookups: Direct access to NWS zone data (forecast zones, fire zones, counties)
• VTEC parsing: Start/end times from VTEC strings
• Multiple data sources: Handles different zone types (fire, forecast, county) automatically

Installation

npm install @radarwave/spc-geo

Quick Start

import { NWSClient, WatchType } from '@radarwave/spc-geo';

// Preferred usage (object form)
const client = new NWSClient({
  feedBaseUrl: 'https://api.weather.gov/alerts/active', // optional, defaults to NWS API
  zoneDataPath: '/my/custom/path' // optional, browser only
});

// Minimal (all defaults)
const client2 = new NWSClient();

// Legacy usage (discouraged):
const client3 = new NWSClient('https://api.weather.gov/alerts/active', '/my/custom/path');
const client4 = new NWSClient('https://api.weather.gov/alerts/active');

// Get all active tornado watches with GeoJSON
const tornadoWatches = await client.GetOperationalWatches(
  { type: WatchType.Tornado }, 
  ["id", "geojson", "start", "to"]
);

// Each watch has a .geojson() method that returns a FeatureCollection
const geojson = tornadoWatches[0].geojson();
console.log(geojson.features.length); // Number of affected zones

Note: The object form is preferred to avoid parameter order issues. zoneDataPath is only needed in the browser if your zone data is not at /zone_data.

Watch Types

The package supports all major NWS watch types:

import { WatchType } from '@radarwave/spc-geo';

// Available types:
WatchType.Tornado           // Tornado Watches
WatchType.SevereThunderstorm // Severe Thunderstorm Watches  
WatchType.FlashFlood        // Flash Flood Watches
WatchType.Flood             // Flood Watches
WatchType.Hurricane         // Hurricane Watches
WatchType.TropicalStorm     // Tropical Storm Watches
WatchType.WinterStorm       // Winter Storm Watches
WatchType.Blizzard          // Blizzard Watches
WatchType.HighWind          // High Wind Watches
WatchType.ExcessiveHeat     // Excessive Heat Watches
WatchType.ExtremeHeat       // Extreme Heat Watches
WatchType.WindChill         // Wind Chill Watches
WatchType.FreezingRain      // Freezing Rain Watches
WatchType.FireWeather       // Fire Weather Watches
WatchType.All               // All active watches

Data Includes

You can specify what data to include in the results:

const includes = [
  "id",        // Watch ID (e.g., "FWA-0005")
  "states",    // Affected state codes
  "ugc",       // UGC codes (county/zone identifiers)
  "counties",  // County names (only from county-type zones)
  "zones",     // Full zone data with geometries
  "headline",  // Watch headline text
  "details",   // Description/Probs (Tornado/Severe only)
  "start",     // Start time (from VTEC)
  "to",        // End time (from VTEC)
  "geojson"    // GeoJSON FeatureCollection
];

Examples

Get Fire Weather Watches with Zone Data

const fireWatches = await client.GetOperationalWatches(
  { type: WatchType.FireWeather },
  ["id", "zones", "geojson", "start", "to"]
);

fireWatches.forEach(watch => {
  console.log(`Watch ${watch.id}:`);
  console.log(`Start: ${watch.start}`);
  console.log(`End: ${watch.to}`);
  console.log(`Zones: ${watch.zones.length}`);
  
  // Get GeoJSON for mapping
  const geojson = watch.geojson();
  console.log(`Features: ${geojson.features.length}`)
});

Process All Active Watches

const allWatches = await client.GetOperationalWatches(
  { type: WatchType.All },
  ["id", "states", "counties", "zones", "geojson"]
);

allWatches.forEach(watch => {
  console.log(`\n${watch.id}:`);
  console.log(`States: ${watch.states.join(', ')}`);
  console.log(`Counties: ${watch.counties.length}`);
  console.log(`Zones: ${watch.zones.length}`);
  
  // Each zone has type, id, and full data
  watch.zones.forEach(zone => {
    console.log(`    ${zone.type}: ${zone.id}`);
  });
});

Get Detailed Tornado Watch Info

const tornadoWatches = await client.GetOperationalWatches(
  { type: WatchType.Tornado },
  ["id", "headline", "details", "geojson"]
);

if (tornadoWatches.length > 0) {
  const watch = tornadoWatches[0];
  console.log(watch.headline);
  
  // Get detailed probabilities and text
  const details = await watch.details();
  console.log(details.maxProbs); // Tornado, wind, hail probabilities
  console.log(details.text);     // Watch discussion text
}

GeoJSON Output

The .geojson() method returns a standard GeoJSON FeatureCollection:

const geojson = watch.geojson();

// Structure:
{
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: { /* zone geometry */ },
      properties: {
        "@id": "https://api.weather.gov/zones/forecast/ILZ058",
        "id": "ILZ058",
        "type": "forecast",
        "name": "Greene",
        "state": "IL",
        "watchid": "FWA-0005",
        // ... other zone properties
      }
    }
  ]
}

Performance Notes

• Zone data is loaded once per request and cached
• County/zone data is split into files by us state or prefix to load only as much as needed.
• Missing zones are logged with warnings

Error Handling

The package handles missing data gracefully:

try {
  const watches = await client.GetOperationalWatches(
    { type: WatchType.Tornado },
    ["id", "geojson"]
  );
  
  if (watches.length === 0) {
    console.log("No tornado watches currently active");
  }
} catch (error) {
  console.error("Failed to fetch watches:", error.message);
}

Zone Data Directory (IMPORTANT for Browser Use)

The SPC Geo package relies on a directory of zone data files (in zone_data/) for geospatial lookups. How you provide this data depends on your environment:

Node.js

• The package will load zone data from the filesystem using the path you provide (e.g., ./node_modules/spc-geo/zone_data/).
• No extra steps are needed if you use the default or a valid local path.

Browser

• The browser cannot access local filesystem paths. It must fetch zone data via HTTP from your web server.
• You must copy or symlink the zone_data directory to your web server's public/static directory.
• Then, set zoneDataPath to the HTTP-accessible path (e.g., /zone_data/).

Example: Copying zone_data for Browser Use

If you installed spc-geo via npm, you can copy the data like this:

cp -r ./node_modules/spc-geo/zone_data ./public/zone_data

Or on Windows:

xcopy /E /I .\node_modules\spc-geo\zone_data .\public\zone_data

Then, in your browser code:

const nwc = new NWSClient({
  zoneDataPath: '/zone_data/'
});

Note: The path must match where your web server serves the files. If you use a different public directory, adjust accordingly.