File Naming Conventions - Spire Weather API Documentation

Reference for understanding Spire Weather file names. See also the GRIB2 and NetCDF glossary entries for file format details.

Standard Forecast Files¶

Pattern¶

{system}.{date}.{time}.{resolution}.{bundle}.{region}.{lead_time}.{format}

Example¶

sof-d.20240115.t00z.0p25.basic.global.f006.grib2

Component	Value	Description
`sof-d`	System	Spire Operational Forecast - Deterministic
`20240115`	Date	Issuance date (YYYYMMDD)
`t00z`	Time	Issuance Time (UTC)
`0p25`	Resolution	0.25° grid spacing
`basic`	Bundle	Data bundle
`global`	Region	Geographic coverage
`f006`	Lead time	Forecast Hour (6 hours ahead)
`grib2`	Format	File format

Component Reference¶

Forecast Systems¶

Code	Description
`sof`	Spire Operational Forecast
`sof-d`	Spire Operational Forecast - Deterministic Forecast
`sof-e`	Spire Operational Forecast - Ensemble Forecast
`srfs`	Spire Regional Forecast System
`cwc`	Current Weather Conditions

Issuance Time¶

Format: tHHz where HH is the hour in UTC.

Code	Time (UTC)
`t00z`	00:00 UTC
`t06z`	06:00 UTC
`t12z`	12:00 UTC
`t18z`	18:00 UTC

Resolution¶

Format: XpYY where X.YY represents degrees.

Code	Degrees	Approximate Distance
`0p027`	0.027°	~3 km
`0p125`	0.125°	~14 km
`0p25`	0.25°	~28 km
`0p5`	0.5°	~55 km
`1p0`	1.0°	~111 km

Bundles¶

Code	Description
`basic`	Standard meteorological variables
`maritime`	Marine parameters
`agricultural`	Agriculture parameters
`aviation`	Aviation weather
`solar`	Solar radiation
`wind`	Wind power data
`precipitation`	Detailed precipitation

Regions¶

Code	Coverage
`global`	Worldwide
`na`	North America
`eu`	Europe
`asia`	Asia
`au`	Australia

Lead Time¶

Format: fHHH where HHH is hours from issuance. See Lead Time.

Code	Meaning
`f000`	Analysis (0 hours)
`f006`	6-hour forecast
`f024`	24-hour forecast
`f048`	48-hour forecast
`f168`	7-day forecast

File Formats¶

Extension	Format
`.grib2`	GRIB2 (WMO standard)
`.nc`	NetCDF
`.csv`	Comma-separated values
`.json`	JSON

Current Weather Files¶

Pattern¶

cwc.{date}.{time}.{resolution}.{bundle}.{region}.{format}

Example¶

cwc.20240115.t16z.0p027.basic.global.grib2

Soil Moisture Files¶

Pattern¶

soil-moisture.{date}.{region}.{format}

Example¶

soil-moisture.20240115.global.nc

Lightning Files¶

Pattern¶

lightning.{date}.{time}.{region}.{format}

Example¶

lightning.20240115.t00z.global.nc

Archive Files¶

Archive files may be delivered as ZIP archives with directory structure:

{date}/
  {hour}/
    {filename}

Example Structure¶

20240115/
  00/
    sof-d.20240115.t00z.0p25.basic.global.f000.grib2
    sof-d.20240115.t00z.0p25.basic.global.f006.grib2
  12/
    sof-d.20240115.t12z.0p25.basic.global.f000.grib2

Custom Product Files¶

Custom products may have organization-specific naming conventions. Contact your Spire representative for documentation of custom file naming.

Parsing File Names in Python¶

import re
from dataclasses import dataclass
from datetime import datetime

@dataclass
class ForecastFileInfo:
    system: str
    date: datetime
    issuance_hour: int
    resolution: float
    bundle: str
    region: str
    lead_hours: int
    format: str

def parse_forecast_filename(filename):
    """Parse a standard forecast filename into components."""
    pattern = r'^(\w+)\.(\d{8})\.t(\d{2})z\.(\d+p\d+)\.(\w+)\.(\w+)\.f(\d{3})\.(\w+)$'
    match = re.match(pattern, filename)

    if not match:
        raise ValueError(f"Could not parse filename: {filename}")

    system, date_str, hour, res_str, bundle, region, lead, fmt = match.groups()

    # Parse resolution (e.g., "0p25" -> 0.25)
    resolution = float(res_str.replace('p', '.'))

    return ForecastFileInfo(
        system=system,
        date=datetime.strptime(date_str, '%Y%m%d'),
        issuance_hour=int(hour),
        resolution=resolution,
        bundle=bundle,
        region=region,
        lead_hours=int(lead),
        format=fmt
    )

# Example usage
filename = "sof-d.20240115.t00z.0p25.basic.global.f006.grib2"
info = parse_forecast_filename(filename)
print(f"System: {info.system}")
print(f"Date: {info.date}")
print(f"Issuance: {info.issuance_hour:02d}Z")
print(f"Resolution: {info.resolution}°")
print(f"Lead time: {info.lead_hours} hours")

Filter Files by Lead Time¶

def filter_by_lead_time(filenames, min_hours=0, max_hours=48):
    """Filter forecast files by lead time range."""
    result = []
    for filename in filenames:
        try:
            info = parse_forecast_filename(filename)
            if min_hours <= info.lead_hours <= max_hours:
                result.append(filename)
        except ValueError:
            continue
    return result

# Get only 0-24 hour forecasts
short_range = filter_by_lead_time(file_list, max_hours=24)