Skip to content

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's valid_time says 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}/runs lists 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 as NaN.
  • 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 the Retry-After seconds and retry.
  • 429 key_cap_exceeded: the key has used the monthly call cap its organization set on it. There is no Retry-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.