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

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 meteorological variables
`maritime`	Marine-specific parameters
`agricultural`	Agriculture-focused variables
`aviation`	Aviation weather parameters
`solar`	Solar radiation data
`wind`	Wind power parameters

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:

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