Forecasts

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

Endpoints¶

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

Server-Side Filtering¶

Both the Point API and Optimized Point API support the X-Fields header to limit which fields are returned. This reduces response size when you only need specific variables.

Example — Request only air temperature and wind speed (Optimized Point API):

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

Example — Request wind gust with times (Point API):

X-Fields: {data{times,values{wind_gust}}}

Example — Filter values while keeping full response structure (Point API, Agricultural bundle):

X-Fields: {meta,data{location,times,values{soil_moisture_0-10cm,soil_moisture_10-40cm,soil_moisture_40-100cm,soil_moisture_100-200cm}}}

The X-Fields value uses a GraphQL-like selection syntax. Specify only the keys you need; omit times or location if you do not need them.

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 are valid for a 6-hour range, so they are only included at lead times in 6-hour intervals (e.g., f000, f006, f012). The first lead time (f000) has no min/max values because it is the start of the forecast window.

For high-frequency time bundles (short_range_high_freq, medium_range_high_freq), lead times between 0–24h are hourly. Min/max fields will not appear at 01:00–05:00, 07:00–11:00, 13:00–17:00, or 19:00–23:00—only at 6-hour boundaries.

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

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

Use time_bundle=medium_range_std_freq for 6-hour intervals and full min/max coverage. The same behavior applies to files from the File API.

Forecast Status¶

GET /forecast/point/status

Check the availability of a forecast product.

Parameters¶

List Forecast Files¶

GET /forecast/file

Retrieve a list of available forecast files.

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¶

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

Example Request¶

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¶

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.

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.

Optimized Point Data Variables¶

The Optimized Point API does not use the same bundles as the standard Point API. Available variables include:

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

Latest Forecast Files¶

GET /forecast/latest/file

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

Parameters¶

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¶

Available Regions¶

Time Bundles for Power¶

Example Request¶

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¶

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¶

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¶

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