REST API¶
The wxchange API is plain HTTPS and JSON at https://api.dev.wxchange.io. This page covers what every
endpoint has in common; the API reference lists each endpoint with
its parameters, request body, responses and errors.
Authentication¶
Send your API key as a bearer token:
Authorization: Bearer sg_live_...
Keys are made in the wxchange app under Settings → API keys; see Getting started. Only the health and version endpoints answer without one.
What you can ask for¶
| Area | Endpoints | Scope |
|---|---|---|
| Models | GET /v1/models, and each model's parameters, forecast steps, runs and analysis times |
read:models |
| Forecasts | POST /v1/models/{model}/point, /timeseries, /route and /area |
read:forecasts |
| Map tiles | GET /v1/tiles/{model}/{parameter}/{z}/{x}/{y}.png: values packed into PNG pixels |
read:forecasts |
| Observations | Surface stations, point observations, storm reports, area observations | read:observations |
| Advisories and ZIPs | Active NWS watches, warnings and advisories; what a ZIP code covers | read:observations |
| Hail and historical radar | Hail probability at a point; historical MRMS radar jobs | read:forecasts |
| MRMS radar | Radar values at a point | see the reference |
| Verification | The Shyft Score per model, its history and regions, rankings, badges, scorecards | see the reference |
Forecast queries¶
The four forecast queries share a shape: a JSON body naming the parameters you want, a
place, and a time.
| Query | Place | Time |
|---|---|---|
point |
lat, lon |
datetime |
timeseries |
lat, lon |
datetimes (a list), or omit it for every forecast step |
route |
waypoints, each with its own lat, lon and datetime |
per waypoint |
area |
bounds and a width × height grid, at most 256 × 256 |
datetime |
- Times are ISO 8601 in UTC (
2026-11-15T18:00:00Z). A time between two forecast steps is interpolated from the steps either side; the response'svalid_timesays what time the values are for. - Runs. Without
run, the newest loaded run of the model answers. Name a run ("run": "2026-11-15T00:00:00Z") to query an older one;GET /v1/models/{model}/runslists them. A run that is not loaded is an error, never a silent fallback. - Places outside a model's grid are an error (
point_out_of_bounds); in an area query, grid cells outside it come back asNaN. - Units are the model's own (temperature in kelvin, wind in m/s) and every value says
its unit:
{"value": 275.3, "units": "K"}. - Area grids come back as flat arrays in row-major order, one per parameter.
Errors¶
Errors are JSON with a stable machine-readable error code and a message for people:
{"error": "model_not_found", "message": "model not found: xyz"}
Branch on error, not on message. The reference lists the codes each endpoint can return.
Limits and retries¶
- 429
rate_limited: too many requests; wait theRetry-Afterseconds and retry. - 429
key_cap_exceeded: the key has used the monthly call cap its organization set on it. There is noRetry-After: the cap lifts when it is raised or the month turns. - 503 with
Retry-After: the request was turned away without running (the service is loading, or too busy to render it in time). Retrying after the stated wait is safe. - 504: the request ran past the 30-second budget. It did run, so do not replay it in a tight loop; narrow it (fewer parameters, a smaller area) instead.
Model listings answer with an ETag; send it back as If-None-Match and an unchanged
answer is a bodiless 304.
Clients¶
The Python SDK wraps the model, forecast, observation, radar, score, advisory and ZIP endpoints. Any other language works with an HTTP client and the bearer header; the reference is generated from the API's OpenAPI description, which you can also feed to a client generator.