Forecasts

Point forecasts, file downloads, route forecasts, and related endpoints.

Endpoints¶

Forecast Products¶

The product parameter selects the forecast product to query. It defaults to sof-d. Access to each product is controlled by your API key’s entitlements; requesting a product that is not in your subscription returns 403 with the list of products you can access.

The point-style endpoints (point, profile, route) support sof-d. The other products are delivered as files through the File API.

AI Weather Products (SAIFS)¶

The SAIFS products are generated by Spire’s AI/ML forecast models rather than traditional numerical weather prediction:

• saifs-wx — AI ensemble weather forecast on a 0.25° grid, refreshed every 6 hours with 6-hourly lead times out to 15 days (360 hours). Every field is delivered twice in the GRIB2 files: the ensemble mean and the ensemble spread (standard deviation), encoded as derived forecasts (derivedForecast 0 and 2). The default file listing shows the hourly time-bundle slice (to 48 hours); use time_bundle=6_hourly_15day to list the full range.

• saifs-s2s — sub-seasonal to seasonal ensemble forecast on a 0.5° grid, refreshed once a day, giving daily and weekly ensemble means and spreads, anomalies, probabilities and percentiles out to 46 days. Bundles are suffixed with a temporal resolution, e.g. surface:daily (files D001–D046, 24-hour windows) or percentiles:weekly (files W001–W006). The suffix is required; surface on its own returns 422 No valid bundles provided.

• saifs-s2s-regimes and saifs-wx-regimes — daily 500 hPa weather-regime probabilities (the share of ensemble members in each regime) as one CSV per region: EUATL (Europe and North Atlantic) and CONUS (North America). The regime lists are in Data Bundles & Variables.

SAIFS data is delivered as files. Use the File API to list and download the files for an issuance:

curl -X GET \
  'https://api.wx.spire.com/forecast/file?product=saifs-s2s' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

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

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

{
  "meta": {
    "count": 780,
    "issuance_time": "2026-09-11T00:00:00+00:00"
  },
  "files": [
    "saifs-s2s.20260911.t00z.0p5.surface.europe.D001.grib2",
    "saifs-s2s.20260911.t00z.0p5.surface.europe.D002.grib2"
  ]
}

Time Bundles¶

The time_bundle parameter selects how a forecast run is sliced into lead times. The values are the same for the point and file endpoints. Record counts are for the point API; the file API returns the same number of files.

Notes:

• 6_hourly_extended and 6_hourly_10day return the same data.

• hourly_6day is available on the Power Forecast and Optimized Point endpoints. On the standard point API it returns 404 unless your subscription includes it.

• Available time bundles depend on your subscription. 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.

• All slices come from the same model run; only the sampling differs.

Time bundles can be combined as a comma-separated list, for example time_bundle=hourly,6_hourly for hourly steps to 48 hours followed by 6-hourly steps to 168 hours. The optimized point endpoint also accepts all, which returns the full 15-day forecast at hourly steps.

Point Forecast¶

GET /forecast/point

Retrieve forecast data for a specific latitude/longitude.

Parameters¶

Example Request¶

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

import requests

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

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

Example Response¶

meta.units lists the unit of every field in the response. location.coordinates.elevation is the model terrain height at the point in metres.

{
  "data": [
    {
      "location": {
        "coordinates": {
          "lat": 40.018672,
          "lon": -105.250537,
          "elevation": 1655.2
        }
      },
      "times": {
        "issuance_time": "2026-09-11T00:00:00+00:00",
        "valid_time": "2026-09-11T00:00:00+00:00"
      },
      "values": {
        "air_pressure_at_sea_level": 101708.8,
        "air_temperature": 287.7,
        "dew_point_temperature": 284.2,
        "eastward_wind": 0.7,
        "northward_wind": 3.0,
        "precipitation_amount": 0.0,
        "precipitation_rate": 0.0,
        "relative_humidity": 79.0,
        "surface_visibility": 24135.3,
        "total_cloud_cover": 100.0,
        "wind_direction": 193.0,
        "wind_gust": 6.5,
        "wind_speed": 3.1
      }
    }
  ],
  "meta": {
    "unit_system": "si",
    "forecast": "Spire SOF-D Forecast",
    "units": {
      "air_pressure_at_sea_level": "Pa",
      "air_temperature": "degreeK",
      "dew_point_temperature": "degreeK",
      "eastward_wind": "m/s",
      "northward_wind": "m/s",
      "precipitation_amount": "mm",
      "precipitation_rate": "mm/h",
      "relative_humidity": "%",
      "surface_visibility": "m",
      "total_cloud_cover": "%",
      "wind_direction": "deg",
      "wind_gust": "m/s",
      "wind_speed": "m/s",
      "air_temperature_max_in_last_6_hours": "degreeK",
      "air_temperature_min_in_last_6_hours": "degreeK",
      "orography": "m"
    }
  }
}

Server-Side Filtering¶

The point, route, optimized point and current weather endpoints support the X-Fields header to limit which fields are returned. This reduces response size when you only need specific variables. The value uses a GraphQL-like selection syntax.

Example — Request only air temperature and wind speed:

X-Fields: {data{values{air_temperature,wind_speed}}}

Example — Request values with times and location (Optimized Point, Route and Current Weather):

X-Fields: {meta,data{location,times,values{air_temperature,wind_speed}}}

On /forecast/point and /forecast/latest/point the mask selects keys inside data{values{...}}; location, times and meta are always returned. The optimized point, current weather and route endpoints also accept masks that name times, location or meta.

Min/Max Temperature¶

The basic bundle includes 6-hour min/max temperature fields:

• air_temperature_max_in_last_6_hours

• air_temperature_min_in_last_6_hours

These values cover the previous 6 hours, so they are only present at lead times that are multiples of 6 hours (f006, f012, …). The first lead time (f000) has no min/max values because it is the start of the forecast window.

With time_bundle=hourly or 3_hourly the fields are therefore absent at the intermediate lead times; with 6_hourly, 6_hourly_extended or 6_hourly_15day every record after the first carries them. The same applies to the corresponding files from the File API.

Example — Request min/max only with X-Fields:

X-Fields: {data{values{air_temperature_min_in_last_6_hours,air_temperature_max_in_last_6_hours}}}

List Forecast Files¶

GET /forecast/file

Retrieve a list of available forecast files. Without filters the response lists every file of the most recent issuance across all bundles and regions in your subscription.

Parameters¶

Example Request¶

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

Example Response¶

For a 00 or 12 UTC issuance the default listing contains the 49 hourly files f000–f048; a 06 or 18 UTC issuance has 25. Add time_bundle=6_hourly_15day to list the 61 six-hourly files out to f360.

{
  "meta": {
    "count": 49,
    "issuance_time": "2026-09-11T00:00:00+00:00"
  },
  "files": [
    "sof-d.20260911.t00z.0p125.basic.global.f000.grib2",
    "sof-d.20260911.t00z.0p125.basic.global.f001.grib2",
    "sof-d.20260911.t00z.0p125.basic.global.f002.grib2"
  ]
}

Download Forecast File¶

GET /forecast/file/{file_id}

Download a specific forecast file.

Path Parameters¶

Example Request¶

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

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

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

Vertical Profile¶

GET /forecast/profile

Retrieve a vertical wind profile at a location. The profile is derived from the basic, maritime-atmos and wind-energy levels of the SOF-D forecast; bundles other than these return 422 No valid bundles provided.

Parameters¶

Response¶

The response is a CoverageJSON CoverageCollection: one Coverage per valid time, each with a VerticalProfile domain. The z axis lists the heights above ground in metres (10, 50, 80, 100, 120, 152, 305, 457, 610, 762, 914, 1067, 1219, 1372, 1524, 1676 and 1829 m); the ranges hold one array per parameter with the same length as z.

{
  "type": "CoverageCollection",
  "parameters": {
    "wind_speed__height_above_ground": {
      "type": "Parameter",
      "observedProperty": {"label": {"en": "wind_speed__height_above_ground"}},
      "unit": {"symbol": "m s**-1"}
    },
    "wind_direction__height_above_ground": {
      "type": "Parameter",
      "observedProperty": {"label": {"en": "wind_direction__height_above_ground"}},
      "unit": {"symbol": "deg"}
    }
  },
  "coverages": [
    {
      "type": "Coverage",
      "domain": {
        "type": "Domain",
        "domainType": "VerticalProfile",
        "axes": {
          "x": {"values": [4.9]},
          "y": {"values": [52.375]},
          "z": {"values": [10.0, 50.0, 80.0, 100.0, 120.0, 152.0, 305.0, 457.0, 610.0, 762.0, 914.0, 1067.0, 1219.0, 1372.0, 1524.0, 1676.0, 1829.0]},
          "t": {"values": ["2026-09-11T06:00:00+00:00"]}
        }
      },
      "ranges": {
        "wind_speed__height_above_ground": {
          "type": "NdArray",
          "dataType": "float",
          "axisNames": ["z"],
          "shape": [17],
          "values": [3.1, 4.8, 5.6, 6.0, 6.3, 6.8, 8.4, 9.2, 9.7, 10.1, 10.4, 10.6, 10.8, 10.9, 11.0, 11.0, 11.1]
        }
      }
    }
  ]
}

Optimized Point Forecast¶

GET /forecast/point/optimized

Retrieve optimized point forecasts for named locations (airports, ports, etc.) using ICAO Code, WMO ID, or UN/LOCODE identifiers.

When are forecasts issued? Spire’s Optimized Point Forecast is updated every hour.

How the Optimized Forecast Is Produced¶

The optimized point system starts from Spire’s global model and improves it for one specific location by combining several forecast systems (Spire’s 12 km global model, other global models at 10 to 26 km, and regional models at 3 to 6 km where available) with observations from the location or nearby weather stations, through machine learning. Because this depends on reliable, well-maintained observations, Spire is selective about the stations it uses.

The forecast is available out of the box for more than 10,000 airports, maritime ports and weather stations. It can also be set up for customer-defined assets such as wind or solar farms, construction sites or mines, using nearby stations and, where the customer provides them, the asset’s own sensors. For solar assets the panel configuration matters: tilt and azimuth angles, and for tracking systems the axis orientation and the tilt and azimuth limits. Contact Spire to configure custom locations.

The core variables are hourly to 15 days (361 steps with time_bundle=all). Hub-height wind and irradiance variables are available where the location has been configured for them.

Parameters¶

Location Format Examples¶

Location examples:

• ICAO: icao:KJFK, icao:YSSY, icao:OMDB

• WMO: wmo:74486, wmo:03772, wmo:72530

• UN/LOCODE: unlocode:NLAMS, unlocode:SGSIN, unlocode:USHOU

Optimized forecasts are available at ~10,000 locations worldwide (airports, maritime ports, and well-known weather stations). Qualified custom locations can be discussed for interested clients.

Bundles¶

Any other bundle name returns 403 with the allowed list.

Optimized Point Data Variables¶

Field names are the JSON keys in data[].values; units are for unit_system=si and are also given in meta.units.

Example Request¶

curl -X GET \
  'https://api.wx.spire.com/forecast/point/optimized?location=icao:KDFW&bundles=basic' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

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

const response = await fetch(
  "https://api.wx.spire.com/forecast/point/optimized?location=icao%3AKDFW&bundles=basic",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Example Response¶

The location object identifies the matched station and includes every identifier it is known by.

{
  "data": [
    {
      "location": {
        "coordinates": {"lat": 32.9, "lon": -97.03},
        "name": "DALLAS/FORT WORTH INTERNATIONAL AIRPORT",
        "icao": "KDFW",
        "wmo": "72259",
        "uuid": "4ac2ae1f-2386-44f6-9c8b-7363da8c51e2"
      },
      "times": {
        "issuance_time": "2026-09-11T11:00:00+00:00",
        "valid_time": "2026-09-11T11:00:00+00:00"
      },
      "values": {
        "air_temperature": 290.2,
        "dew_point_temperature": 289.2,
        "relative_humidity": 94.0,
        "air_pressure_at_mean_sea_level": 101750.0,
        "surface_air_pressure": 101800.0,
        "ceiling": 1073.8,
        "total_cloud_cover": 75.0,
        "visibility": 10000.0,
        "wind_speed": 5.7,
        "wind_direction": 210.0,
        "wind_gust": 8.5,
        "precipitation_rate": 0.31,
        "precipitation_amount_1hr": 0.3,
        "probability_of_precipitation_1hr": 100.0,
        "conditional_probability_of_rain": 100.0,
        "snowfall_amount_total": 0.0,
        "heat_index": null,
        "wind_chill": null
      }
    }
  ],
  "meta": {
    "unit_system": "si",
    "forecast": "Spire Optimized Point Forecast",
    "units": {
      "air_temperature": "degreeK",
      "precipitation_rate": "mm/h",
      "snowfall_amount_total": "cm",
      "visibility": "m"
    }
  }
}

Bulk Optimized Point Files¶

GET /forecast/optimized/bulk
GET /forecast/optimized/bulk/{file_id}

For customers with many optimized locations, the bulk endpoint delivers the forecasts of a pre-configured group of locations as one file. Every time the optimized forecast is refreshed (hourly), a new bulk file is generated for each group.

Groups are configured by Spire, not through the API. To set one up, provide a name for the group, the list of locations it contains, and the preferred format (CSV or JSON). Once configured, listing the endpoint without parameters returns the files available; prefix, suffix and contains narrow the list.

File names follow point.{date}.t{HHMM}z.{group}.{csv|json}, for example point.20240523.t1100z.my-ports.csv for the 11:00 UTC issuance of 23 May 2024. Download a file by appending its name to the endpoint path, following the redirect.

Latest Forecast Files¶

GET /forecast/latest/file

Get the most recent forecast files, regardless of issuance time.

Parameters¶

The response has the same shape as List Forecast Files, with meta.issuance_time set to the issuance that was selected.

Latest Point Forecast¶

GET /forecast/latest/point

Get the most recent forecast for a point, regardless of issuance time.

Parameters¶

Same as /forecast/point but without the issuance_time and time_bundle parameters. The response has the same shape as the point forecast.

Power Forecast¶

GET /forecast/power

Retrieve power forecasts of aggregated power generation from wind or solar assets over a predetermined geographic region. The forecast predicts actual power output (in megawatts) rather than raw meteorological variables.

How Power Forecasts Are Produced¶

Instead of forecasting the weather at each asset, the power endpoint forecasts the total generation of all wind or solar assets in a region, in megawatts. Two kinds of sources are offered, listed by /forecast/power/sources. The Spire AI sources (srfs-*-ai) are machine-learning models trained on the region’s aggregated historical generation together with historical forecasts from Spire’s high-resolution model. The physical sources (*-physical) convert the wind speed or solar radiation of a weather model into power with the same conversion for every model, so that forecasts driven by different models can be compared like for like. Because each power forecast depends on its driving weather model, it is published shortly after that model’s run completes, and its horizon and update times follow that model.

Parameters¶

Available Regions¶

Time Bundles for Power¶

The end of the range depends on the source (see max_lead_hours in Power Forecast Sources).

An unknown value returns {"message": "Unknown time bundle ..."}.

Example Request¶

curl -X GET \
  'https://api.wx.spire.com/forecast/power?type=solar,wind&region=uk,france&time_bundle=hourly_6day&source=srfs-europe-physical' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/forecast/power",
    params={
        "type": "solar,wind",
        "region": "uk,france",
        "time_bundle": "hourly_6day",
        "source": "srfs-europe-physical",
    },
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/forecast/power?type=solar,wind&region=uk,france&time_bundle=hourly_6day&source=srfs-europe-physical",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Example Response¶

The first valid_time is one hour after the issuance because each value is the generation over the previous hour.

{
  "data": [
    {
      "region": "france",
      "source": "srfs-europe-physical",
      "type": "wind",
      "times": {
        "issuance_time": "2026-09-11T06:00:00Z",
        "valid_time": "2026-09-11T07:00:00Z"
      },
      "values": {
        "power": 2336.8
      }
    },
    {
      "region": "france",
      "source": "srfs-europe-physical",
      "type": "wind",
      "times": {
        "issuance_time": "2026-09-11T06:00:00Z",
        "valid_time": "2026-09-11T08:00:00Z"
      },
      "values": {
        "power": 2521.2
      }
    }
  ]
}

Output Fields¶

Power Forecast Sources¶

GET /forecast/power/sources

List the forecast sources available for power forecasts, including their issuance hours and maximum lead times. Use this endpoint to discover valid values for the source parameter of the Power Forecast endpoint.

Example Request¶

curl -X GET \
  'https://api.wx.spire.com/forecast/power/sources' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

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

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

Example Response¶

{
  "sources": [
    {
      "name": "ecmwf-physical",
      "issuance_hours": [0, 6, 12, 18],
      "max_lead_hours": 240
    },
    {
      "name": "sofd-physical",
      "issuance_hours": [0, 6, 12, 18],
      "max_lead_hours": 360
    },
    {
      "name": "srfs-europe-physical",
      "issuance_hours": [6, 12],
      "max_lead_hours": 144
    }
  ]
}

Route Forecast¶

POST /forecast/route

Retrieve forecast data along a route defined by waypoints and times. Unlike the point API where the location is fixed, the route API follows a moving position through time (e.g., a vessel path).

A single route API call returns the variables of the requested bundles at every waypoint. A maximum of 120 waypoints may be included per request.

Point Versus Route¶

A point request keeps the location fixed and returns the whole forecast period for it. A route request follows a position that moves through time: a vessel that is in port today, at sea tomorrow and in another port next week. For each waypoint the API returns the forecast valid at that place and that time. Waypoint times do not have to match forecast steps; the response reports the step actually used in valid_time and your request in requested_valid_time.

Query Parameters¶

Request Body¶

The body contains a route object with a waypoints array; name is optional. Bundles are selected with the bundles query parameter, not in the body. Each waypoint has lat, lon and an ISO 8601 time.

{
  "route": {
    "name": "my_route",
    "waypoints": [
      {
        "lat": 26.71,
        "lon": -22.41,
        "time": "2024-01-15T12:00:00"
      },
      {
        "lat": 26.54,
        "lon": -22.48,
        "time": "2024-01-15T13:00:00"
      },
      {
        "lat": 26.23,
        "lon": -22.62,
        "time": "2024-01-15T14:00:00"
      }
    ]
  }
}

Example Request¶

curl -X POST 'https://api.wx.spire.com/forecast/route?bundles=basic,maritime' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "route": {"name": "atlantic_crossing", "waypoints": [
      {"lat": 26.71, "lon": -22.41, "time": "2024-01-15T12:00:00"},
      {"lat": 26.54, "lon": -22.48, "time": "2024-01-15T13:00:00"},
      {"lat": 26.23, "lon": -22.62, "time": "2024-01-15T14:00:00"}
    ]}
  }'

import requests

response = requests.post(
    "https://api.wx.spire.com/forecast/route",
    params={"bundles": "basic,maritime"},
    headers={"spire-api-key": "YOUR_API_KEY"},
    json={
        "route": {
            "name": "atlantic_crossing",
            "waypoints": [
                {"lat": 26.71, "lon": -22.41, "time": "2024-01-15T12:00:00"},
                {"lat": 26.54, "lon": -22.48, "time": "2024-01-15T13:00:00"},
                {"lat": 26.23, "lon": -22.62, "time": "2024-01-15T14:00:00"},
            ],
        },
    },
)
data = response.json()

const response = await fetch("https://api.wx.spire.com/forecast/route?bundles=basic,maritime", {
  method: "POST",
  headers: {
    "spire-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    route: {
      name: "atlantic_crossing",
      waypoints: [
        { lat: 26.71, lon: -22.41, time: "2024-01-15T12:00:00" },
        { lat: 26.54, lon: -22.48, time: "2024-01-15T13:00:00" },
        { lat: 26.23, lon: -22.62, time: "2024-01-15T14:00:00" },
      ],
    },
  }),
});
const data = await response.json();

Response¶

One record per waypoint, in the same shape as the point forecast (including meta.units and location.coordinates.elevation). When a requested waypoint time does not align with an available forecast time, the API returns data for the nearest available time and reports both:

{
  "location": {
    "coordinates": {"lat": 26.71, "lon": -22.41, "elevation": 0.0}
  },
  "times": {
    "issuance_time": "2024-01-13T12:00:00+00:00",
    "valid_time": "2024-01-15T12:00:00+00:00",
    "requested_valid_time": "2024-01-15T13:10:00+00:00"
  },
  "values": {
    "air_temperature": 293.1,
    "sea_surface_wave_significant_height": 1.8
  }
}