File Products Guide - Spire Weather API Documentation

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.0p25.basic.global.f000.grib2

Component	Description	Example
`forecast_system`	Model identifier	`sof-d`
`issuance_date`	Date (YYYYMMDD)	`20240115`
`issuance_time`	Run time	`t00z`
`resolution`	Resolution (grid spacing)	`0p25` (0.25°)
`bundle`	Bundle	`basic`
`region`	Coverage area	`global`
`forecast_hour`	Lead Time	`f000` (analysis)
`format`	File format	`grib2`

Listing Available Files¶

Get a list of available files for your subscription:

Shell

Python

Node.js

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()

Response:

{
  "meta": {
    "count": 29
  },
  "files": [
    "sof-d.20240115.t00z.0p25.basic.global.f000.grib2",
    "sof-d.20240115.t00z.0p25.basic.global.f006.grib2",
    "sof-d.20240115.t00z.0p25.basic.global.f012.grib2"
  ]
}

Downloading Files¶

Download a specific file by name:

Shell

Python

Node.js

curl -OJL -X GET \
  'https://api.wx.spire.com/forecast/file/sof-d.20240115.t00z.0p25.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.0p25.basic.global.f000.grib2",
    headers={"spire-api-key": "YOUR_API_KEY"},
    allow_redirects=True,
)

with open("sof-d.20240115.t00z.0p25.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.0p25.basic.global.f000.grib2",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);

const fileStream = createWriteStream("sof-d.20240115.t00z.0p25.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.0p25.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:

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/forecast/file?issuance=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": "2024-01-15T00:00:00Z"},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

By Region¶

Available regions vary by subscription. Common options:

global - Worldwide coverage
north_america - North American domain
europe - European domain

Latest Files¶

Get the most recent files regardless of issuance:

Shell

Python

Node.js

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

Custom Products¶

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

Shell

Python

Node.js

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

Best Practices¶

Check file list first - Verify files exist before attempting downloads
Use redirects - Always follow HTTP redirects (-L in curl, allow_redirects=True in Python)
Handle errors - Implement retry logic for network issues
Parallel downloads - Download multiple files concurrently for efficiency
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