Forecasts - Spire Weather API Documentation

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

Endpoints¶

Method	Endpoint	Description
GET	`/forecast/point`	Get forecast at a point
GET	`/forecast/point/status`	Check forecast availability
GET	`/forecast/file`	List forecast files
GET	`/forecast/file/{file_id}`	Download a forecast file
GET	`/forecast/profile`	Get vertical profile
GET	`/forecast/point/optimized`	Get optimized point forecast
GET	`/forecast/point/optimized/status`	Check optimized forecast status
GET	`/forecast/optimized/bulk`	List bulk optimized files
GET	`/forecast/optimized/bulk/{file_id}`	Download bulk optimized file
GET	`/forecast/latest/file`	List latest forecast files
GET	`/forecast/latest/point`	Get latest point forecast
GET	`/forecast/power`	Get power forecast
POST	`/forecast/route`	Get route forecast

Point Forecast¶

GET /forecast/point

Retrieve forecast data for a specific latitude/longitude.

Parameters¶

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`bundles`	string	No	Comma-separated Bundle names
`issuance`	string	No	ISO 8601 Issuance Time
`valid_time`	string	No	ISO 8601 Valid Time or interval
`time_bundle`	string	No	Time Bundle grouping option
`unit_system`	string	No	SI Units (default) or US Units
`product`	string	No	Product identifier
`tz`	string	No	Timezone identifier

Example Request¶

Shell

Python

Node.js

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": {
    "unit_system": "si",
    "forecast": "Spire Operational Forecast"
  },
  "data": [
    {
      "location": {
        "coordinates": {
          "lat": 40.018672,
          "lon": -105.250537
        }
      },
      "times": {
        "issuance_time": "2024-01-15T00:00:00",
        "valid_time": "2024-01-15T00:00:00"
      },
      "values": {
        "relative_humidity": 75.67,
        "air_temperature": 258.00,
        "dew_point_temperature": 257.25,
        "northward_wind": 1.55,
        "eastward_wind": -1.97
      }
    }
  ]
}

Forecast Status¶

GET /forecast/point/status

Check the availability of a forecast product.

Parameters¶

Parameter	Type	Required	Description
`issuance`	string	No	ISO 8601 issuance time
`product`	string	No	Product identifier
`bundles`	string	No	Bundle names

List Forecast Files¶

GET /forecast/file

Retrieve a list of available forecast files.

Parameters¶

Parameter	Type	Required	Description
`issuance`	string	No	ISO 8601 issuance time
`bundles`	string	No	Comma-separated Bundle names
`time_bundle`	string	No	Time Bundle grouping option
`regions`	string	No	Comma-separated region names

Example Request¶

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

Example 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"
  ]
}

Download Forecast File¶

GET /forecast/file/{file_id}

Download a specific forecast file.

Path Parameters¶

Parameter	Type	Required	Description
`file_id`	string	Yes	The filename to download

Example Request¶

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

Vertical Profile¶

GET /forecast/profile

Retrieve a vertical atmospheric profile at a location.

Parameters¶

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`bundles`	string	No	Bundle names
`issuance`	string	No	ISO 8601 issuance time
`valid_time`	string	No	Valid Time or interval
`time_bundle`	string	No	Time Bundle grouping
`product`	string	No	Product identifier

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.

Parameters¶

Parameter	Type	Required	Description
`location`	string	No	Location identifier (ICAO, WMO, UN/LOCODE)
`location_id`	string	No	UUID location identifier
`bundles`	string	No	Bundle names
`issuance`	string	No	ISO 8601 issuance time
`valid_time`	string	No	Valid Time or interval
`time_bundle`	string	No	Time Bundle grouping
`unit_system`	string	No	`si` or `us`
`tz`	string	No	Timezone

Location Format Examples¶

Type	Example	Description
ICAO Code	`icao:KDFW`	Airport identifier
WMO ID	`wmo:72259`	Synoptic station ID
UN/LOCODE	`unlocode:IDJKT`	Port/city code

Example Request¶

Shell

Python

Node.js

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

Latest Forecast Files¶

GET /forecast/latest/file

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

Parameters¶

Parameter	Type	Required	Description
`bundles`	string	No	Bundle names
`regions`	string	No	Region names

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 issuance parameter.

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.

Parameters¶

Parameter	Type	Required	Description
`type`	string	Yes	`wind`, `solar`, or both comma-separated
`region`	string	Yes	One or more regions, comma-separated
`time_bundle`	string	No	Time grouping (see below)
`issuance_time`	string	No	ISO 8601 issuance time (default: most recent)
`source`	string	No	NWP data source (default: SRFS)

Available Regions¶

Region
`austria`
`france`
`germany`
`hungary`
`netherlands`
`uk`

Time Bundles for Power¶

Time Bundle	Description
`hourly`	2-day hourly forecast
`3_hourly`	Every 3 hours to day 6
`6_hourly`	Every 6 hours to day 6
`hourly_6day`	Every hour to day 6 (recommended for maximum time series)

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/forecast/power?type=solar,wind&region=uk,france&time_bundle=hourly_6day' \
  -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"},
    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",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Example Response¶

{
  "data": [
    {
      "region": "france",
      "source": "srfs",
      "type": "wind",
      "times": {
        "issuance_time": "2024-09-05T12:00:00+00:00",
        "valid_time": "2024-09-05T12:00:00+00:00"
      },
      "values": {
        "power": 2336.83
      }
    },
    {
      "region": "france",
      "source": "srfs",
      "type": "wind",
      "times": {
        "issuance_time": "2024-09-05T12:00:00+00:00",
        "valid_time": "2024-09-05T13:00:00+00:00"
      },
      "values": {
        "power": 2521.23
      }
    }
  ]
}

Output Fields¶

Field	Description
`region`	The region for this data point
`source`	Background NWP data source (SRFS = Spire high-resolution forecast)
`type`	`wind` or `solar`
`power`	Predicted power output over the previous hour, in megawatts (MW)

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 all supported weather variables you have access to from all data bundles. A maximum of 120 waypoints may be included per request.

Query Parameters¶

Parameter	Type	Required	Description
`issuance_time`	string	No	ISO 8601 issuance time (default: most recent)
`tz`	string	No	Timezone for response times (default: local time at coordinate)
`unit_system`	string	No	SI Units (default) or US Units

Request Body¶

The request body contains the route definition and bundle selection:

{
  "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"
      }
    ]
  },
  "bundles": "basic,maritime"
}

Example Request¶

Shell

Python

Node.js

curl -X POST 'https://api.wx.spire.com/forecast/route' \
  -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"}
    ]},
    "bundles": "basic,maritime"
  }'

import requests

response = requests.post(
    "https://api.wx.spire.com/forecast/route",
    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"},
            ],
        },
        "bundles": "basic,maritime",
    },
)
data = response.json()

const response = await fetch("https://api.wx.spire.com/forecast/route", {
  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" },
      ],
    },
    bundles: "basic,maritime",
  }),
});
const data = await response.json();

Time Alignment¶

When requested waypoint times do not align with available forecast times, the API returns data for the nearest available time. The response includes both the matched time and the originally requested time:

{
  "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"
  }
}