Quick Start Guide - Spire Weather API Documentation

This guide will help you make your first API calls to retrieve weather data.

Prerequisites¶

A valid Spire Weather API Key
curl or a programming language with HTTP client support

Your First Request¶

Let’s retrieve a Point Forecast for Boulder, Colorado:

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

url = 'https://api.wx.spire.com/forecast/point'
params = {
    'lat': 40.018672,
    'lon': -105.250537,
    'bundles': 'basic'
}
headers = {'spire-api-key': 'YOUR_API_KEY'}

response = requests.get(url, params=params, headers=headers)
data = response.json()

for forecast in data['data']:
    print(f"{forecast['times']['valid_time']}: {forecast['values']['air_temperature']}K")

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

for (const forecast of data.data) {
  console.log(`${forecast.times.valid_time}: ${forecast.values.air_temperature}K`);
}

Example Response¶

{
  "meta": {
    "unit_system": "si",
    "forecast": "Spire SOF-D Forecast",
    "units": {
      "relative_humidity": "%",
      "air_temperature": "degreeK",
      "dew_point_temperature": "degreeK",
      "northward_wind": "m/s",
      "eastward_wind": "m/s"
    }
  },
  "data": [
    {
      "location": {
        "coordinates": {
          "lat": 40.018672,
          "lon": -105.250537,
          "elevation": 1655.0
        }
      },
      "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
      }
    }
  ]
}

Common Use Cases¶

Get Current Weather¶

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

List Available Forecast Files¶

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

Get Latest Forecast¶

Use the /forecast/latest/point endpoint to get the most recent forecast without specifying an Issuance Time:

Shell

Python

Node.js

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

import requests

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

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

Selecting Data Bundles¶

Data is organized into bundles based on use case. Specify bundles in your request:

Bundle	Description
`basic`	Standard surface meteorological variables
`clouds`	Cloud ceiling and low, mid and high cloud cover
`precipitation`	Precipitation type, snowfall and composite reflectivity
`thunderstorm`	Convective indices (CAPE, CIN, helicity, shear)
`maritime`	Sea surface temperature, waves, currents, salinity
`maritime-atmos`	Wind at 50 m for offshore operations
`maritime-wave`	Wind-wave and swell components
`maritime-wave-ext`	Maximum wave height, peak and zero-crossing periods
`agricultural`	Soil moisture and temperature, surface fluxes
`wind-energy`	Wind and air density at 80, 100 and 120 m
`solar-energy`	Accumulated shortwave and longwave radiation
`upper-air`	Isobaric levels 1000 to 1 hPa (file endpoints only)
`aviation`	Flight-level winds, turbulence and icing (file endpoint only)

The opt-in basic-accumulation, precipitation-accumulation and solar-energy-accumulation bundles add windowed 1-, 3- and 6-hour amounts at the point endpoint. See the Data Bundles & Variables reference for every field in every bundle.

Request multiple bundles by comma-separating:

Shell

Python

Node.js

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

import requests

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

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

Unit Systems¶

By default, responses use SI Units. Request US Units with the unit_system parameter. us returns temperatures in Celsius, pressure in hPa, wind in mph and visibility in miles; us-f is the same with temperatures in Fahrenheit:

Shell

Python

Node.js

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

import requests

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

See Units Reference for complete unit details.

Next Steps¶

File Products Guide - Download GRIB2 forecast files
API Reference - Complete endpoint documentation
Interactive Notebooks - Live code examples