Skip to content

Getting started

Three steps: an API key, a first request, and somewhere to work with the results.

1. Create an API key

Sign in to the wxchange app and open Settings → API keys. Create a key and copy it when it is shown: it starts sg_live_ and is shown only once.

Treat the key like a password. Keep it out of source code and notebooks you share; the examples below read it from an environment variable:

export WXCHANGE_API_KEY=sg_live_...

A key carries scopes. Forecast queries need read:forecasts, the model listings read:models, and observations, storm reports, advisories and ZIP lookups need read:observations.

2. Make a request

The API is at https://api.dev.wxchange.io. Send the key as a bearer token on every request:

curl -s -H "Authorization: Bearer $WXCHANGE_API_KEY" https://api.dev.wxchange.io/v1/models

The answer lists the models your key can use, each with its slug: the name every model path takes. Pick one and ask for its parameters, with their units and forecast steps:

curl -s -H "Authorization: Bearer $WXCHANGE_API_KEY" https://api.dev.wxchange.io/v1/models/gfs/parameters

Then query a forecast. A point query takes a location, the parameters you want and the time the forecast should be valid for:

curl -s -X POST https://api.dev.wxchange.io/v1/models/gfs/point \
  -H "Authorization: Bearer $WXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "lat": 41.26,
        "lon": -95.94,
        "parameters": ["temperature_2m", "wind_speed_gust_surface"],
        "datetime": "'"$(date -u +%Y-%m-%dT%H:00:00Z)"'"
      }'
{
  "model": "gfs",
  "run_time": "2026-11-15T00:00:00Z",
  "point": {"lat": 41.26, "lon": -95.94},
  "valid_time": "2026-11-15T04:00:00Z",
  "values": {
    "temperature_2m": {"value": 275.3, "units": "K"},
    "wind_speed_gust_surface": {"value": 5.2, "units": "m/s"}
  }
}

Values come back in the units the model publishes (here kelvin and metres per second), and each one says which. With no run in the request, the newest loaded run answers; a time between two forecast steps is interpolated.

The REST API overview explains times, runs, units and errors; the API reference lists every endpoint with its request and response.

3. Work with the results

In a hosted notebook

Open the notebooks and sign in with your wxchange account. You get a JupyterLab with the Python SDK and its charting extras installed, opened on a welcome notebook. Paste your key into it:

from stormlore import Client

client = Client(api_key="sg_live_...")
now = client.forecast.point("gfs", (41.26, -95.94), ["temperature_2m"])
now.to_dataframe()

A notebook is a scratch space: it closes after 10 minutes idle or an hour in any case, and nothing in it is kept. Download anything you want to keep.

In your own code

Any HTTP client works; send the bearer header and JSON bodies as above. In Python, the Python SDK does it for you: it reads WXCHANGE_API_KEY, retries what is safe to retry, turns results into pandas DataFrames and xarray Datasets, and draws charts and maps. Its forecasts guide is the place to start.

When something goes wrong

Every error is JSON with a machine-readable code and a message for people:

{"error": "parameter_not_found", "message": "parameter not found: temp"}
Status Means
400 The request is malformed: a missing field or an unreadable time.
401 No key, or a key the API does not accept (mistyped, expired or revoked).
403 The key is valid but lacks the scope, or your organization has not subscribed to the model.
404 The model, parameter or run does not exist.
422 The point is outside the model's grid, or the time outside what it covers.
429 Too many requests (rate_limited, wait for Retry-After) or the key's monthly cap is reached (key_cap_exceeded).
503 The API is busy or still loading; retry after Retry-After.