Current Weather - Spire Weather API Documentation

Real-time weather observations and conditions.

Overview¶

Current Weather Conditions (cwc) is a gridded analysis of the weather right now, produced every hour on a global 3 km grid (0.027°) from observations and Spire’s forecast models. Each hourly analysis becomes available about 35 minutes after the top of the hour. It carries the most common surface variables: temperature, dew point and relative humidity at 2 m, wind at 10 m with gusts, mean sea-level pressure, precipitation rate and type, visibility, incoming shortwave radiation and effective cloud cover.

The data is served as GRIB2 files per region (one file per hour, kept for the past 72 hours) and as JSON for a single coordinate. See the cwc bundle for the field list.

Endpoints¶

Method	Endpoint	Description
GET	`/current/weather/file`	List current weather files
GET	`/current/weather/file/{file_id}`	Download a current weather file
GET	`/current/weather/point`	Get current weather at a point

List Current Weather Files¶

GET /current/weather/file

Retrieve a list of available current weather condition files. Current weather conditions (cwc) are an analysis product of their own: files are produced every hour at 0.027° resolution for nine regions (global, africa, asia, atlantic, conus, europe, north-america_central-america_caribbean, south-america, south-west_pacific), all with the single bundle basic.

Parameters¶

Parameter	Type	Required	Description
`time`	string	No	ISO 8601 timestamp or time range
`regions`	string	No	Comma-separated list of regions

Example Request¶

Shell

Python

Node.js

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

Example Response¶

{
  "meta": {
    "count": 648
  },
  "files": [
    "cwc.20240115.t16z.0p027.basic.africa.grib2",
    "cwc.20240115.t16z.0p027.basic.asia.grib2",
    "cwc.20240115.t16z.0p027.basic.atlantic.grib2",
    "cwc.20240115.t16z.0p027.basic.conus.grib2",
    "cwc.20240115.t16z.0p027.basic.europe.grib2",
    "cwc.20240115.t16z.0p027.basic.global.grib2"
  ]
}

Filter to one hour and region with time and regions, for example ?time=2024-01-15T16:00:00Z&regions=europe.

Download Current Weather File¶

GET /current/weather/file/{file_id}

Download a specific current weather 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/current/weather/file/cwc.20240115.t16z.0p027.basic.global.grib2' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/current/weather/file/cwc.20240115.t16z.0p027.basic.global.grib2",
    headers={"spire-api-key": "YOUR_API_KEY"},
    allow_redirects=True,
)

with open("cwc.20240115.t16z.0p027.basic.global.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/current/weather/file/cwc.20240115.t16z.0p027.basic.global.grib2",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);

const fileStream = createWriteStream("cwc.20240115.t16z.0p027.basic.global.grib2");
Readable.fromWeb(response.body).pipe(fileStream);

Get Current Weather at Point¶

GET /current/weather/point

Retrieve current weather conditions for a specific location.

Parameters¶

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`time`	string	No	ISO 8601 timestamp or time range
`unit_system`	string	No	`si` (default), `us` or `us-f`
`tz`	string	No	Timezone identifier, or `local`

Headers¶

Header	Description
`X-Fields`	Field Mask for response filtering

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/current/weather/point?lat=40.0&lon=-105.0' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/current/weather/point",
    params={"lat": 40.0, "lon": -105.0},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

Example Response¶

{
  "meta": {
    "unit_system": "si",
    "forecast": "Spire Current Weather Conditions",
    "units": {
      "air_pressure_at_sea_level": "Pa",
      "air_temperature": "degreeK",
      "dew_point_temperature": "degreeK",
      "eastward_wind": "m/s",
      "northward_wind": "m/s",
      "precipitation_rate": "mm/h",
      "relative_humidity": "%",
      "surface_net_downward_shortwave_flux": "J/m**2",
      "surface_visibility": "m",
      "wind_direction": "deg",
      "wind_gust": "m/s",
      "wind_speed": "m/s"
    }
  },
  "data": [
    {
      "location": {
        "coordinates": {
          "lat": 40.0,
          "lon": -105.0
        }
      },
      "times": {
        "issuance_time": "2024-01-15T16:00:00+00:00",
        "valid_time": "2024-01-15T16:00:00+00:00"
      },
      "values": {
        "air_pressure_at_sea_level": 101776.7,
        "air_temperature": 275.5,
        "dew_point_temperature": 273.8,
        "eastward_wind": 2.5,
        "northward_wind": 3.9,
        "effective_cloud_amount": 35.3,
        "precipitation_rate": 0.0,
        "predominant_precipitation_type": "no_precipitation",
        "relative_humidity": 65.2,
        "surface_net_downward_shortwave_flux": 509.0,
        "surface_visibility": 49804.4,
        "wind_direction": 225.0,
        "wind_gust": 5.8,
        "wind_speed": 5.3
      }
    }
  ]
}

issuance_time and valid_time are identical for an analysis product. predominant_precipitation_type is a string such as no_precipitation, rain, snow, freezing_rain or ice_pellets. See the Current Weather Conditions bundle for the full variable list.

Field Filtering¶

Use the X-Fields header to request specific fields:

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/current/weather/point?lat=40.0&lon=-105.0' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'X-Fields: {data{values{air_temperature,wind_speed}}}'

import requests

response = requests.get(
    "https://api.wx.spire.com/current/weather/point",
    params={"lat": 40.0, "lon": -105.0},
    headers={
        "spire-api-key": "YOUR_API_KEY",
        "X-Fields": "{data{values{air_temperature,wind_speed}}}",
    },
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/current/weather/point?lat=40.0&lon=-105.0",
  {
    headers: {
      "spire-api-key": "YOUR_API_KEY",
      "X-Fields": "{data{values{air_temperature,wind_speed}}}",
    },
  }
);
const data = await response.json();