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. |