File Products Guide

Spire Weather provides forecast data as downloadable GRIB2 files for users who need complete gridded datasets.

Overview¶

File products are ideal when you need:

• Complete global or regional coverage

• Integration with existing GRIB2 workflows

• Efficient bulk data processing

• Archive Data access

File Naming Convention¶

Files follow this naming pattern:

forecast_system.issuance_date.issuance_time.resolution.bundle.region.forecast_hour.format

Example: sof-d.20240115.t00z.0p125.basic.global.f000.grib2

Other products follow the same pattern with their own codes: SRFS files use 03km and a lead time with minutes (f006m00), SAIFS-S2S files use 0p5 and a daily or weekly step (D001, W001), and the weather-regime products are CSV files without a bundle or lead-time component. See File Naming Conventions.

Products¶

The product parameter of /forecast/file selects which forecast system’s files are listed. It defaults to sof-d.

Current weather conditions (cwc) are a product of their own, served by /current/weather/file. Soil moisture and lightning files have their own endpoints as well. Access to each product is controlled by your subscription.

Listing Available Files¶

Get a list of available files for your subscription:

curl -X GET \
  'https://api.wx.spire.com/forecast/file?bundles=basic&regions=global' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/file",
    params={"bundles": "basic", "regions": "global"},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/forecast/file?bundles=basic&regions=global",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Response:

{
  "meta": {
    "count": 49,
    "issuance_time": "2024-01-15T00:00:00+00:00"
  },
  "files": [
    "sof-d.20240115.t00z.0p125.basic.global.f000.grib2",
    "sof-d.20240115.t00z.0p125.basic.global.f001.grib2",
    "sof-d.20240115.t00z.0p125.basic.global.f002.grib2"
  ]
}

Without a time_bundle, the listing for a 00 or 12 UTC issuance contains the hourly files f000 to f048; 06 and 18 UTC issuances contain f000 to f024. Add time_bundle=6_hourly_15day (or another Time Bundle) to list the 6-hourly files out to the end of the forecast range.

Downloading Files¶

Download a specific file by name:

curl -OJL -X GET \
  'https://api.wx.spire.com/forecast/file/sof-d.20240115.t00z.0p125.basic.global.f000.grib2' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/file/sof-d.20240115.t00z.0p125.basic.global.f000.grib2",
    headers={"spire-api-key": "YOUR_API_KEY"},
    allow_redirects=True,
)

with open("sof-d.20240115.t00z.0p125.basic.global.f000.grib2", "wb") as f:
    f.write(response.content)

import { createWriteStream } from "fs";
import { Readable } from "stream";

const response = await fetch(
  "https://api.wx.spire.com/forecast/file/sof-d.20240115.t00z.0p125.basic.global.f000.grib2",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);

const fileStream = createWriteStream("sof-d.20240115.t00z.0p125.basic.global.f000.grib2");
Readable.fromWeb(response.body).pipe(fileStream);

Python Example¶

Download all files for the latest issuance:

import requests

root_url = 'https://api.wx.spire.com/forecast/file'
headers = {'spire-api-key': 'YOUR_API_KEY'}

# Get list of available files
params = {'bundles': 'basic', 'regions': 'global'}
file_list = requests.get(root_url, params=params, headers=headers).json()

# Download each file
for filename in file_list['files']:
    print(f'Downloading: {filename}')

    file_url = f'{root_url}/{filename}'
    response = requests.get(file_url, headers=headers, allow_redirects=True)

    with open(filename, 'wb') as f:
        f.write(response.content)

Working with GRIB2 Files¶

Using xarray and cfgrib¶

import xarray as xr

# Open a GRIB2 file
ds = xr.open_dataset('sof-d.20240115.t00z.0p125.basic.global.f000.grib2',
                     engine='cfgrib')

# Access temperature data
temperature = ds['t2m']  # 2-meter temperature
print(temperature)

Using eccodes¶

import eccodes

with open('forecast.grib2', 'rb') as f:
    while True:
        gid = eccodes.codes_grib_new_from_file(f)
        if gid is None:
            break

        name = eccodes.codes_get(gid, 'name')
        values = eccodes.codes_get_values(gid)
        print(f'{name}: min={values.min():.2f}, max={values.max():.2f}')

        eccodes.codes_release(gid)

Filtering Files¶

By Issuance Time¶

Request files from a specific model run:

curl -X GET \
  'https://api.wx.spire.com/forecast/file?issuance_time=2024-01-15T00:00:00Z' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/file",
    params={"issuance_time": "2024-01-15T00:00:00Z"},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/forecast/file?issuance_time=2024-01-15T00:00:00Z",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

By Region¶

Available regions vary by subscription. The global forecast (sof-d) is cut into these regions:

• global

• africa

• asia

• atlantic

• conus

• europe

• north-america_central-america_caribbean

• south-america

• south-west_pacific

SRFS is available for conus and europe; SAIFS-WX for global, conus and europe; SAIFS-S2S for global, europe and north-america_central-america_caribbean. Your key may expose additional custom regions. Use the region codes exactly as listed; the file list endpoint shows the codes available to your account. See the Operational Reference.

Latest Files¶

Get the most recent files regardless of issuance:

curl -X GET \
  'https://api.wx.spire.com/forecast/latest/file?bundles=basic' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/latest/file",
    params={"bundles": "basic"},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/forecast/latest/file?bundles=basic",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Custom Products¶

If you have custom file products configured, access them via:

curl -X GET \
  'https://api.wx.spire.com/custom/file' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/custom/file",
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/custom/file",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Best Practices¶

1. Check file list first - Verify files exist before attempting downloads

2. Use redirects - Always follow HTTP redirects (-L in curl, allow_redirects=True in Python)

3. Handle errors - Implement retry logic for network issues

4. Parallel downloads - Download multiple files concurrently for efficiency

5. Verify integrity - Check file sizes match expected values

Next Steps¶

• Forecasts API Reference - Complete endpoint details

• File Naming Reference - Detailed naming conventions

• Data Visualization Notebook - Visualizing GRIB2 data