Operational Reference

Reference for forecast update schedules, time bundles, regions, unit caveats, accumulated fields, and system status.

Forecast Update Schedule¶

Spire’s global atmospheric forecast model runs 4 times per day. The first lead times of each run appear in the API approximately at the times below; the remaining lead times follow over the next hours and a run is nominally complete about seven hours after issuance (see Forecast Resolution, Range, and Refresh Rate).

Optimized Point Forecast Updates¶

The Optimized Point Forecast system (/forecast/point/optimized) updates every hour.

Current Weather Conditions Updates¶

The current weather conditions (/current/weather/) update every hour.

Time Bundles¶

Time bundles control the temporal resolution and extent of forecast data returned by the API. Use the time_bundle parameter to select which time grouping you want.

The 06 and 18 UTC runs of the global forecast cover 24 hours: hourly returns 25 records and 6_hourly returns 5 for those issuances. When time_bundle is omitted, the API uses the first time bundle licensed on your key, which differs between customers; always pass time_bundle explicitly.

Time bundles can be combined as a comma-separated list. time_bundle=hourly,6_hourly returns hourly steps for the first 48 hours followed by 6-hourly steps to 168 hours (69 records or files for a 00/12 UTC run).

Data Retention¶

The live API keeps the forecasts of the last three days (about eleven issuances of the global forecast) and the current-weather files of the last 72 hours. Older forecasts can be made available on request; older weather is served by the Archive Data service.

This table is the reference for time bundle names. Other pages link here rather than repeating it.

Example¶

Request only hourly data for the first 2 days:

curl -X GET \
  'https://api.wx.spire.com/forecast/point?lat=40.0&lon=-105.0&bundles=basic&time_bundle=hourly' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/point",
    params={
        "lat": 40.0,
        "lon": -105.0,
        "bundles": "basic",
        "time_bundle": "hourly",
    },
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/forecast/point?lat=40.0&lon=-105.0&bundles=basic&time_bundle=hourly",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Regions¶

Forecast file data is organized by geographic region. Available regions depend on your subscription.

Bounding boxes are approximate; the regions overlap so that every area of interest is covered by at least one regional file. Regions apply to file downloads and WMS layers; point requests are accepted anywhere inside the regions your key is subscribed to. Customers with a custom region have it configured as their default and can omit the parameter.

The weather-regime products use the region labels CONUS and EUATL (Europe and North Atlantic) in their file names.

Unit Differences Between APIs¶

Some variables have different units depending on whether they are returned by the Point/Route API (JSON) or the File API (GRIB2):

The JSON response lists the unit of every field in meta.units; the GRIB2 unit is in each message’s units key.

Working with Accumulated Fields¶

Several variables in the forecast data are accumulated from the start of the forecast (issuance time). These include:

• Accumulated precipitation

• Accumulated snowfall

• Accumulated radiation (shortwave/longwave, incoming/outgoing)

Deriving Hourly Values¶

To get the hourly amount for an accumulated field, subtract the previous time step’s value from the current one:

# Example: derive hourly precipitation from accumulated values
hourly_precip = []
for i in range(1, len(data)):
    current = data[i]['values']['precipitation_amount']
    previous = data[i-1]['values']['precipitation_amount']
    hourly_precip.append(current - previous)

Accumulation Bundles¶

For convenience, Spire offers “accumulation” bundles that provide pre-computed 1-hour, 3-hour, and 6-hour accumulation amounts, eliminating the need to compute differences manually:

• basic-accumulation — 1h/3h/6h precipitation amounts (precipitation_amount_1hr, _3hr, _6hr)

• precipitation-accumulation — 1h/3h/6h snowfall amounts (snowfall_amount_1hr, _3hr, _6hr)

• solar-energy-accumulation — 1h/3h/6h amounts of the five radiation fields (surface_net_downward_shortwave_flux_1hr, and so on)

An N-hour field is returned at every lead time that is a multiple of N: with time_bundle=hourly you receive the 1-, 3- and 6-hour fields, with 3_hourly the 3- and 6-hour fields, and with 6_hourly the 6-hour fields only.

These are available at the Point API endpoint and are opt-in. Contact Spire if you are interested.

GRIB2 File Concatenation¶

GRIB2 files from Spire can be concatenated together. This is useful for combining multiple lead times or bundles into a single file for processing:

cat sof-d.20240115.t00z.0p125.basic.global.f000.grib2 \
    sof-d.20240115.t00z.0p125.basic.global.f006.grib2 \
    sof-d.20240115.t00z.0p125.basic.global.f012.grib2 \
    > combined.grib2

System Status¶

Spire Weather provides an online status page to monitor the health of the API and weather data products. The status page can be accessed at: Spire Weather Status

Monitored Components¶

Status Values¶

Impact of Degraded Performance¶

When a forecast component shows degraded performance:

• Short-range forecast (first 24–36 hours) may be based on the previous model run and have slightly reduced accuracy

• The medium-range forecast may be missing the last few hours of its range (e.g., only 9.5 days instead of 10)

• Historical/archived data remains unaffected