wxchange REST API (1.0.0)

Download OpenAPI specification:

Weather data REST API serving forecasts from the platform's model store.

All query endpoints accept ISO 8601 datetime strings instead of integer forecast steps. Temporal interpolation is applied automatically when the requested datetime falls between two forecast steps. An optional run field allows querying a specific model run.

Load, timeouts and retries

  • 503 overloaded with Retry-After — a tile render or an area query could not get a render slot within the configured wait. The request was shed, not run: retry after the stated seconds.
  • 504 — the request ran past the 30 s whole-request budget. It did run, so do not replay it blindly.
  • 429 rate_limited with Retry-After — besides the per-key and visitor quotas, a deployment may bound how many unknown bearers one client IP can have checked per minute. Only a bearer this service has not seen recently counts; a known key or session is never refused by it.
  • 429 key_cap_exceeded — the API key has reached the monthly call cap its organization set on it; X-Sentinel-Cap says <used>/<limit>. No Retry-After: it lifts when the cap is raised or the month turns.

Either 429 (rate_limited or key_cap_exceeded) can answer any authenticated route, including one whose responses below list no 429.

system

Health and administration

Health check

Returns API health status and loaded model information.

Status values:

  • healthy: At least one model has loaded variables (200)
  • empty: No data ingested yet — up and ready to serve empty results (200)
  • loading: Store exists but models aren't loaded yet (503)

A model that failed to load is listed in degraded_models (served from last-good metadata); it does not change the aggregate status.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "loaded_models": [
    ],
  • "degraded_models": [
    ],
  • "snapshot_id": "abc123",
  • "last_reload": "2026-03-04T00:15:30Z",
  • "snapshot_committed_at": "2026-03-04T00:15:12Z",
  • "models": {
    },
  • "repos_walked": true,
  • "build": {
    }
}

Build version

What is running: the release stamp, the commit and build time, and the Helm chart that deployed it. The same path and keys in every Storm service. Public, never metered or rate limited, and sent Cache-Control: no-cache.

version is vX.Y.Z on a tagged release build and vX.Y.Z-N-g<sha7> for a build N commits past that tag (what staging runs between releases). A build outside CI reports vX.Y.Z+local.

Responses

Response samples

Content type
application/json
{
  • "service": "storm-glass",
  • "version": "v0.4.0-12-g3831ee5",
  • "git_sha": "3831ee5000000000000000000000000000000000",
  • "built_at": "2026-10-13T02:11:00Z",
  • "chart": "storm-glass-0.2.0"
}

Reload the OGC config tree

Re-reads the OGC API config tree (OGC_CONFIG_DIR) now when its files changed. A tree that fails to load is rejected (422) and the last good config keeps serving. The background reload loop does the same every reload interval. Requires the admin:platform scope.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "outcome": "reloaded",
  • "generation": 1,
  • "error": "string"
}

Reload data

Runs one reload cycle now and answers when it is done: the same plan the background loop runs, reading only the models the store's snapshot diff changed (every model when there is no diff, e.g. on a pod that has served nothing yet), plus every degraded model, even one still waiting out its retry backoff. Sentinel tier answers are all asked again. Requires the admin:platform scope.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "reloaded",
  • "snapshot_id": "def456",
  • "models_loaded": [
    ],
  • "duration_ms": 1250
}

Reload one model

Re-reads one model's metadata at the snapshot already served, through the served store, and carries every other model unchanged. It cannot move the snapshot forward for one model: the others would then sit behind a snapshot id the next diff starts from, and their commits in between would never be seen. The next background cycle picks up anything newer as usual.

A model whose load fails answers an error (503 when the store is unreachable); the store keeps serving its last-good metadata and lists it in /v1/health degraded_models. Requires the admin:platform scope.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: hrrr

Model slug (the public identifier; equals the name for platform models).

Responses

Response samples

Content type
application/json
{
  • "status": "reloaded",
  • "snapshot_id": "def456",
  • "models_loaded": [
    ],
  • "duration_ms": 1250
}

Cache statistics

Returns the chunk, tile and past-run cache statistics. Requires the admin:platform scope.

The counts are this process's own, since it started: they reset on a pod restart and are per pod, not per tier. The caches are pumped before being read, so a zero is a real zero rather than a stale estimate.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "mode": "chunked",
  • "memory_used_bytes": 6442450944,
  • "memory_budget_bytes": 8589934592,
  • "hit_count": 1847293,
  • "miss_count": 4521,
  • "hit_rate": 0.9976,
  • "eviction_count": 312,
  • "entry_count": 48291,
  • "metadata_resident_bytes": 47185920,
  • "caches": {
    },
  • "prewarm": {
    }
}

models

Model and parameter metadata

List models

Returns the weather models the caller can use, with their metadata: every model with a public catalog listing (an unentitled query answers 403 subscribe_required) and every model the caller is entitled to. A model the query gate would answer 404 is not listed. Platform admins see every loaded model.

Authorizations:
BearerAuth
header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "models": [
    ]
}

Get model parameters

Returns available parameters for a specific model, including metadata like units and available forecast steps.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "run_time": "2026-03-04T12:00:00Z",
  • "parameters": [
    ]
}

Get model steps

Returns available forecast steps (hours) for a model. Works even for models in "loading" status since steps come from coordinates.

run_time is the run that serves. A newer run takes over only once its last valid time reaches the served run's, or once its last declared step has landed; until then it is reported as ingesting_run, and the served run keeps answering.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "run_time": "2026-03-04T12:00:00Z",
  • "steps": [
    ],
  • "status": "ready",
  • "ingesting_run": {
    }
}

Get analysis frame times

Returns the observation-frame valid times available for an analysis-layout model (e.g. mrms), in ascending order. This is the timeline source for analysis products, which have a flat time axis instead of forecast runs and steps.

Each entry is a non-empty ISO 8601 UTC timestamp (a stored frame time that is not a valid datetime is not served, here or anywhere else) that can be passed verbatim as the time query parameter to the point (/v1/point/mrms) and tile (/v1/tiles/{model}/{parameter}/{z}/{x}/{y}) endpoints.

Forecast models (GFS, HRRR) have no flat time axis and return 400 — use /runs and /steps for those.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: mrms

Model slug (the public identifier; equals the name for platform models).

header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "model": "mrms",
  • "layout": "analysis",
  • "times": [
    ],
  • "count": 2,
  • "status": "ready"
}

List model runs

Lists all available runs for a model, read from the same store snapshot the model's metadata is served from. The listing is cached per model until that model is next reloaded (a new hour landing, a new run, or a tier change), so repeat calls between reloads do not read the store again. Useful for debugging ingestion status and seeing which runs are complete.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "loaded_run": "2026-03-04T12Z",
  • "runs": [
    ]
}

query

Weather data queries

Point query

Returns interpolated weather values at a single point for a specific datetime.

Temporal interpolation is applied automatically when the requested datetime falls between two forecast steps. If it exactly matches a step, no temporal interpolation is needed.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

Request Body schema: application/json
required
lat
required
number <float>

Latitude in degrees

lon
required
number <float>

Longitude in degrees

parameters
required
Array of strings

Weather parameters to retrieve

datetime
required
string <date-time>

ISO 8601 datetime for the query. Values are temporally interpolated between the two nearest forecast steps if not an exact match.

run
string <date-time>

Optional model run to query (ISO 8601). If omitted, uses the latest loaded run. If specified but not found, returns an error.

Responses

Request samples

Content type
application/json
{
  • "lat": 40.7,
  • "lon": -73.9,
  • "parameters": [
    ],
  • "datetime": "2026-03-04T18:00:00Z",
  • "run": "2026-03-04T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "run_time": "2026-03-04T12:00:00Z",
  • "point": {
    },
  • "valid_time": "2026-03-04T18:00:00Z",
  • "values": {
    }
}

Timeseries query

Returns interpolated weather values at a single point across multiple datetimes.

If datetimes is omitted, returns values at all available forecast steps (converted to valid_time ISO 8601 strings). If provided, temporal interpolation is applied for each requested datetime.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

Request Body schema: application/json
required
lat
required
number <float>
lon
required
number <float>
parameters
required
Array of strings
datetimes
Array of strings <date-time> [ items <date-time > ]

Optional list of ISO 8601 datetimes. If omitted, returns values at all available forecast steps (converted to valid_time datetimes). Each datetime is temporally interpolated independently.

run
string <date-time>

Optional model run to query (ISO 8601).

Responses

Request samples

Content type
application/json
{
  • "lat": 40.7,
  • "lon": -73.9,
  • "parameters": [
    ],
  • "datetimes": [
    ],
  • "run": "2026-03-04T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "run_time": "2026-03-04T12:00:00Z",
  • "point": {
    },
  • "series": [
    ]
}

Route query

Returns interpolated weather values along a series of waypoints, each with its own datetime. Temporal interpolation is applied at each waypoint independently.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: gfs

Model slug (the public identifier; equals the name for platform models).

Request Body schema: application/json
required
required
Array of objects (Waypoint)
parameters
required
Array of strings
run
string <date-time>

Optional model run to query (ISO 8601).

Responses

Request samples

Content type
application/json
{
  • "waypoints": [
    ],
  • "parameters": [
    ],
  • "run": "2026-03-04T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "model": "gfs",
  • "run_time": "2026-03-04T12:00:00Z",
  • "waypoints": [
    ]
}

Area query

Returns a grid of interpolated values over a bounding box at a specific datetime.

Each parameter is interpolated independently over the grid. Temporal interpolation is applied if the datetime falls between forecast steps. Out-of-bounds points are filled with NaN. Grid values are returned as flat row-major arrays.

Maximum resolution is 256x256.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: hrrr

Model slug (the public identifier; equals the name for platform models).

Request Body schema: application/json
required
required
object (AreaBounds)

Bounding box for an area query.

width
required
integer <int32> [ 1 .. 256 ]

Width of the output grid in pixels. Max 256.

height
required
integer <int32> [ 1 .. 256 ]

Height of the output grid in pixels. Max 256.

parameters
required
Array of strings

Weather parameters to retrieve. Each is interpolated independently.

datetime
required
string <date-time>

ISO 8601 datetime for the query. Temporal interpolation is applied if the datetime falls between forecast steps.

run
string <date-time>

Optional model run to query (ISO 8601).

Responses

Request samples

Content type
application/json
{
  • "bounds": {
    },
  • "width": 128,
  • "height": 128,
  • "parameters": [
    ],
  • "datetime": "2026-03-04T18:00:00Z",
  • "run": "2026-03-04T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "model": "hrrr",
  • "run_time": "2026-03-04T12:00:00Z",
  • "valid_time": "2026-03-04T18:00:00Z",
  • "bounds": {
    },
  • "width": 128,
  • "height": 128,
  • "grids": {
    }
}

hail

ML-based hail probability predictions

Hail probability query

Returns ML-computed hail probability at a point from the hrrr_diagnostic model for a specific datetime.

Includes standard thresholds (0.25", 1.0", 2.0"), Weibull distribution parameters, and optional custom threshold probability. Temporal interpolation is applied if the datetime falls between forecast steps.

Custom threshold formula: P(hail >= h) = prob_occur * exp(-(h / scale)^shape)

Authorizations:
BearerAuth
Request Body schema: application/json
required
lat
required
number <float>

Latitude in degrees

lon
required
number <float>

Longitude in degrees

datetime
required
string <date-time>

ISO 8601 datetime for the query.

run
string <date-time>

Optional model run to query (ISO 8601).

threshold
number <float>

Custom hail size threshold in inches for prob_custom

Responses

Request samples

Content type
application/json
{
  • "lat": 35.2,
  • "lon": -97.4,
  • "datetime": "2026-03-04T18:00:00Z",
  • "run": "2026-03-04T12:00:00Z",
  • "threshold": 1.5
}

Response samples

Content type
application/json
{
  • "model": "hrrr_diagnostic",
  • "run_time": "2026-03-04T12:00:00Z",
  • "point": {
    },
  • "valid_time": "2026-03-04T18:00:00Z",
  • "prob_any": 0.35,
  • "prob_severe": 0.12,
  • "prob_significant": 0.03,
  • "max_size": 1.2,
  • "dist_shape": 2.1,
  • "dist_scale": 0.8,
  • "prob_occur": 0.45,
  • "prob_custom": 0.08,
  • "custom_threshold": 1.5
}

tiles

Data tiles (8-bit grey by default, 16-bit rg16 on request) for map visualization

Data tile

Returns a 256x256 8-bit RGBA PNG tile for the given model, parameter, and ZXY tile coordinates, encoding each pixel's value over the parameter's fixed range. NaN or out-of-bounds pixels are transparent black (all four channels 0). encoding picks the packing:

  • grey8 (default): one rounded 8-bit level in R, G and B (A = 255). value = min + R / 255 * (max - min). Rounded since this release; a pixel may sit one level above the truncated grey served before.
  • rg16 (opt-in): a rounded 16-bit level, R the high byte and G the low byte (B = 0, A = 255). value = min + (R * 256 + G) / 65535 * (max - min). Exact to 1/65535 of the range; typically 1.5-3x the bytes of grey8, up to ~15x on smooth fields.

min/max come from the X-Value-Min/X-Value-Max headers: the range of the run rendered, so a tile pinned to a past run (run) carries that run's (the metadata endpoint reports the served run's); a 304 carries none, and the stored copy keeps its own. X-Pixel-Encoding names the encoding served. The range is fixed per parameter, read from the array's display_range attr, which Stormgard writes from its parameter catalog; an array without one is encoded over 0-1 (range_source: default on the metadata). No tile is scaled to its own data. Each encoding is cached as its own tile.

Tiles are Web Mercator (EPSG:3857). Each pixel is the value at that pixel's centre on the Mercator map (rows evenly spaced in Mercator y); no pixel samples a tile edge. At low zoom, where a tile's pixels are wider than the model's grid cells, a pixel is instead the maximum (severe fields such as reflectivity, MESH, hail probability, precipitation) or the mean (everything else) of every cell it covers; categorical fields, k-d-tree (IDW) customer grids and projections other than Lambert conformal keep the centre value. Which zooms aggregate is fixed per model, the same for every tile.

For hail_probability pseudo-parameter, the server reads Weibull distribution parameters and computes P(hail >= threshold) per pixel.

Caching. A tile pinned with run whose hours all landed a few reload intervals ago is final: stable for its TTL and revalidated cheaply. It is public, max-age=3600 with a strong ETag, and a matching If-None-Match is answered 304 without rendering the tile (after the usual authentication and access checks). A loop over a past run's frames then fetches each frame about once an hour. The TTL is bounded so that a model turning private, or a cache ban, takes effect within an hour. Final means a public_free model (as for any shared tile), a forecast run (never an analysis model such as mrms, whose frames are overwritten in place), and either the served run with every hour the tile reads landed a few reload intervals ago, or an older complete run first seen complete that long ago. Anything else keeps public, max-age=300 (an unpinned tile always does: "latest" moves) or private, no-store. The ETag covers the server build, the run's store path and every input that changes the bytes (model, run, parameter, z/x/y, time, encoding, threshold).

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: hrrr

Model slug (the public identifier; equals the name for platform models).

parameter
required
string
Example: temperature_surface
z
required
integer [ 0 .. 8 ]

Zoom level (0-8)

x
required
integer

Tile X coordinate

y
required
string

Tile Y coordinate (with .png suffix)

query Parameters
time
required
string <date-time>
Example: time=2026-03-04T18:00:00Z

ISO 8601 datetime

run
string <date-time>

Optional model run (ISO 8601)

threshold
number <float>

Hail threshold in inches (for hail_probability tiles). Must be a positive, finite number (else 400). Ignored by every other parameter.

encoding
string
Default: "grey8"
Enum: "grey8" "rg16"

Pixel encoding: grey8 (default, 8-bit grey in R, G and B) or rg16 (16 bits, R high byte, G low byte). Anything else is 400 invalid_encoding.

header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "error": "model_not_found",
  • "message": "model not found: xyz"
}

Tile metadata

Returns the min/max value range, units, available forecast steps and pixel encoding for a parameter. The min/max values decode tile pixels back to real values (grey8: min + R / 255 * (max - min); rg16: min + (R * 256 + G) / 65535 * (max - min)) and equal the X-Value-Min/X-Value-Max headers on its served run's tiles (a tile pinned to a past run carries that run's range). hail_probability answers wherever its tiles render.

Authorizations:
BearerAuth
path Parameters
model
required
string
Example: hrrr

Model slug (the public identifier; equals the name for platform models).

parameter
required
string
Example: temperature_surface
header Parameters
If-None-Match
string
Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877"

The ETag of a copy you already hold (a comma list, or *). If the body you would get is the same, the answer is 304 Not Modified with no body. Compared weakly: W/"…" and "…" match alike.

Responses

Response samples

Content type
application/json
{
  • "model": "hrrr",
  • "parameter": "temperature_surface",
  • "min_value": 200,
  • "max_value": 330,
  • "units": "K",
  • "steps": [
    ],
  • "encoding": "grey8",
  • "encodings": [
    ],
  • "levels": {
    },
  • "range_source": "attr"
}

radar

On-demand historical MRMS radar ingestion

Start a historical MRMS radar ingestion job

Delegates to wxchange-ingest to ingest a ±3h MRMS radar window centered on center_time into the normal Icechunk store. Returns immediately with a job_id; poll GET /v1/radar/historical/{job_id} for progress. Once status is ready, the ingested window is queryable through the tile API (/v1/tiles/mrms/...) exactly like any other model — there is no separate read path or rendered artifact for this feature.

Authorizations:
BearerAuth
Request Body schema: application/json
required
center_time
required
string <date-time>

Center of the fixed ±3h historical ingestion window (ISO 8601, UTC). Must be after the MRMS archive floor (2020-10-01) and not in the future.

Responses

Request samples

Content type
application/json
{
  • "center_time": "2026-06-01T18:00:00Z"
}

Response samples

Content type
application/json
{
  • "job_id": "3f2a9e1c-9d3b-4b7a-9c1a-8e6f1a2b3c4d",
  • "status": "ingesting",
  • "total_files": 180,
  • "completed_files": 96,
  • "error": null,
  • "center_time": "2026-06-01T18:00:00Z",
  • "expires_at": "2026-06-03T18:00:00Z"
}

Poll a historical radar ingestion job

Returns the job's current status and progress, proxied from wxchange-ingest. status progresses pending → discovering → ingesting → ready (or failed).

Authorizations:
BearerAuth
path Parameters
job_id
required
string <uuid>
Example: 3f2a9e1c-9d3b-4b7a-9c1a-8e6f1a2b3c4d

The job_id returned by POST /v1/radar/historical (a UUID)

Responses

Response samples

Content type
application/json
{
  • "job_id": "3f2a9e1c-9d3b-4b7a-9c1a-8e6f1a2b3c4d",
  • "status": "ingesting",
  • "total_files": 180,
  • "completed_files": 96,
  • "error": null,
  • "center_time": "2026-06-01T18:00:00Z",
  • "expires_at": "2026-06-03T18:00:00Z"
}

observations

Point-observation data (SPC/NCEI storm reports) — a separate PostGIS store, not the Zarr forecast/analysis models

Observation catalog

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Every published observation source (METAR, RAOB, storm reports, …) with its row count and time coverage — the general "what observations do we have?" discovery entry point — followed by the customer sources the caller owns or subscribes to (a platform admin, who can read any customer source by key, gets the same: only its own and subscribed ones here), each with name, kind (points | polygons), owner (whether the caller owns it) and the current mapping's units. Listed sources the caller has not subscribed to are not here (they are in the marketplace). Platform entries carry none of those fields. Every entry carries its source's category — observation or advisory (served at /v1/advisories) — when the registry knows it.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

List point observations

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Source-agnostic bbox + time-window list of point observations (e.g. MADIS METAR surface stations, or any published source), as a GeoJSON FeatureCollection. Each feature's properties carries the raw decoded observation fields the source writes (for METAR: temperature_c, dewpoint_c, wind_speed_ms, raw_metar, …; for RAOB: a levels array).

bbox is required. start/end default to the last 24 hours and may not span more than 365 days. Keyset-paginated via next_cursor.

Without source, only published platform sources are read — never a customer source. A customer source's features nest their values under properties.values (numbers) and their text under properties.attributes, with properties.units ({variable: unit}, from the mapping version in force when the row was last written; a reading whose variables straddle a unit change labels the older variable with the newer unit). A customer key not yet in the registry, carrying the caller's own owner tag or entitled to the caller, refreshes it once (at most once per 5 s per owner tag per pod), so a source just created or subscribed to is readable at once.

Authorizations:
BearerAuth
query Parameters
bbox
required
string
Example: bbox=-125,24,-66,50

min_lon,min_lat,max_lon,max_lat

source
string
Example: source=madis_metar

Restrict to one source key (e.g. madis_metar). Omit for all published sources. A customer source key (c_<tag>_<name>) is read by its owner (the account, or a member of the owning org), an entitled subscriber, or a platform admin; a listed source answers anyone else 403 subscribe_required, any other 404 observation_source_not_found.

start
string <date-time>

Defaults to 24 hours before end.

end
string <date-time>

Defaults to now.

cursor
string

Opaque keyset cursor from a previous response's next_cursor.

limit
integer [ 1 .. 2000 ]

Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "next_cursor": "string"
}

List observing stations

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Catalog of fixed observing stations (e.g. MADIS METAR sites) as a GeoJSON FeatureCollection, optionally spatially filtered by bbox. Each feature's id is the station id; properties carries station_id, name, elevation_m, and any extra station metadata. Not cursor-paginated — clamped by limit.

Authorizations:
BearerAuth
query Parameters
source
string
Example: source=madis_metar

Restrict to one source key (e.g. madis_metar). Omit for all published sources. A customer source key (c_<tag>_<name>) is read by its owner (the account, or a member of the owning org), an entitled subscriber, or a platform admin; a listed source answers anyone else 403 subscribe_required, any other 404 observation_source_not_found.

bbox
string
Example: bbox=-125,24,-66,50

Optional min_lon,min_lat,max_lon,max_lat spatial filter.

limit
integer [ 1 .. 2000 ]

Max stations. Default 500, max 2000; a value outside 1..2000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Station observation timeseries

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

All observations at a single station over a time window, ordered by observed_at, as a GeoJSON FeatureCollection. Keyset-paginated.

Authorizations:
BearerAuth
path Parameters
station_id
required
string
Example: KMCI
query Parameters
source
string
Example: source=madis_metar

Restrict to one source key. Omit to search all published sources for the station. A customer source key (c_<tag>_<name>) is read by its owner (the account, or a member of the owning org), an entitled subscriber, or a platform admin; a listed source answers anyone else 403 subscribe_required, any other 404 observation_source_not_found.

start
string <date-time>

Defaults to 24 hours before end.

end
string <date-time>

Defaults to now.

cursor
string
limit
integer [ 1 .. 2000 ]

Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "next_cursor": "string"
}

Observations near a point

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Observations within radius_km of (lat, lon), ordered nearest-first, as a GeoJSON FeatureCollection. Each feature's properties.distance_m is the great-circle distance (metres) from the query point. Distance ordering does not compose with keyset pagination, so this endpoint caps by limit with no next_cursor.

Authorizations:
BearerAuth
query Parameters
lat
required
number
Example: lat=39.1
lon
required
number
Example: lon=-94.6
radius_km
required
number [ 0 .. 500 ]
Example: radius_km=100

Search radius in kilometres. Clamped to 500.

source
string
Example: source=madis_metar

Restrict to one source key. Omit for all published sources. A customer source key (c_<tag>_<name>) is read by its owner (the account, or a member of the owning org), an entitled subscriber, or a platform admin; a listed source answers anyone else 403 subscribe_required, any other 404 observation_source_not_found.

start
string <date-time>
end
string <date-time>
limit
integer [ 1 .. 2000 ]

Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "next_cursor": "string"
}

List area observations (polygons over a time interval)

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

The polygons of one area source — a customer polygons source (kind polygons in the catalog, of either category) or a platform area source such as nws_wwa — whose interval [start, end) overlaps the window, as a GeoJSON FeatureCollection. A polygon overlaps when it starts before the window's end and ends (or is open-ended) after its start; a polygon that began more than 31 days before the window's start is not returned. Customer sources follow the same access rule as /v1/observations/points.

start/end default to the last 24 hours and may not span more than 31 days. Ordered by (start, id), keyset-paginated via next_cursor.

Authorizations:
BearerAuth
query Parameters
source
required
string
Example: source=c_0a1b2c3d_hail_swaths

The area source key. A points source is refused with 400.

bbox
string
Example: bbox=-100,30,-90,40

min_lon,min_lat,max_lon,max_lat — only polygons intersecting it.

start
string <date-time>

Defaults to 24 hours before end.

end
string <date-time>

Defaults to now.

cursor
string

Opaque keyset cursor from a previous response's next_cursor.

limit
integer [ 1 .. 1000 ]

Page size. Default 100, max 1000; a value outside 1..1000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "next_cursor": "string"
}

List storm reports

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Bbox + time-window filtered list of SPC/NCEI storm reports (discrete hail/wind/tornado events), as a GeoJSON FeatureCollection.

bbox is required — an unbounded, nationwide query would blow past useful spatial-index selectivity across the full report history. start/end default to the last 24 hours and may not span more than 365 days.

Paginated via keyset cursor (next_cursor in the response, echoed back as the cursor query param for the following page) rather than offset, so paging stays a fast indexed range scan no matter how deep into the history a client goes.

Authorizations:
BearerAuth
query Parameters
bbox
required
string
Example: bbox=-98.5,34.0,-96.0,36.5

min_lon,min_lat,max_lon,max_lat

start
string <date-time>
Example: start=2026-06-01T00:00:00Z

Defaults to 24 hours before end.

end
string <date-time>
Example: end=2026-06-02T00:00:00Z

Defaults to now.

report_type
string
Example: report_type=hail
state
string
Example: state=OK

Two-letter state code.

source
string
Example: source=spc_storm_reports

Restrict to one source key (e.g. spc_storm_reports). Omit for all published sources. Platform sources only — a customer source key answers 404 observation_source_not_found.

cursor
string

Opaque keyset cursor from a previous response's next_cursor.

limit
integer [ 1 .. 2000 ]

Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 limit_out_of_range naming the cap.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "next_cursor": null
}

Storm report catalog

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Available sources, observed report types, and per-source date coverage — useful for populating filter UI before running a query.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ],
  • "report_types": [
    ]
}

Storm reports rolled up by county

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

County-level roll-up of storm-report counts within a bbox: one entry per county, each with a total and a by_year histogram. Built for choropleth shading — a client fetches this once, then shades counties by the count in whatever time window it has selected, client-side.

Keyed on 5-digit county FIPS. Only NCEI Storm Events reports carry FIPS, so this is the historical-archive view (recent SPC preliminary reports, which have no FIPS, are not included). Counties with no matching report simply don't appear.

No boundary geometry is returned — county polygons are static reference data the client owns and joins to this response on fips.

Not paginated (the payload is one row per county in view). The time window has a wider cap than the per-event endpoints' 365 days — a choropleth wants a multi-year histogram — but it is bounded: an omitted start defaults to the last 2 years (not all-history), and a span beyond 5 years is rejected 400. This bound is deliberate: for a wide bbox the query seq-scans every partition in range, so an all-history aggregation would scan the whole store. A request that is still too broad may return 400 ("narrow the bbox or shorten the time range") rather than run away.

Authorizations:
BearerAuth
query Parameters
bbox
required
string
Example: bbox=-103.0,33.5,-94.0,37.0

min_lon,min_lat,max_lon,max_lat

start
string <date-time>
Example: start=2024-01-01T00:00:00Z

Defaults to 2 years before end. Span may not exceed 5 years.

end
string <date-time>
Example: end=2026-01-01T00:00:00Z

Defaults to now.

report_type
string
Example: report_type=hail

Restrict the roll-up to one peril (hail, wind, tornado).

source
string
Example: source=ncei_storm_events

Restrict to one source key. Omit for all published sources. Platform sources only — a customer source key answers 404 observation_source_not_found.

Responses

Response samples

Content type
application/json
{
  • "counties": [
    ]
}

Get a single storm report

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Looks up one storm report by its obs_id (the id on its GeoJSON Feature), as returned by the list endpoint.

Authorizations:
BearerAuth
path Parameters
obs_id
required
string
Example: spc:hail:9f3ac21d4b7e

Responses

Response samples

Content type
application/json
{
  • "type": "Feature",
  • "id": "madis:metar:KMCI:1700000000",
  • "geometry": {
    },
  • "properties": {
    }
}

advisories

NWS watches, warnings and advisories plus customer advisory sources — the current set, from the observation store — and the ZIP code lookup

Advisory event types with counts, every provider

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

Event types (Tornado Warning, Flood Watch, …) with how many advisories carry each, most frequent first, over the active set (NWS's current /alerts/active plus the customer polygons live now) of every advisory source the caller reads (see /v1/advisories; source narrows). ugc, zip and lat+lon narrow the count to the advisories that list a zone or ZIP, or cover the point, exactly as they narrow /v1/advisories. History (active=false, since, until) was retired: 400.

Authorizations:
BearerAuth
query Parameters
active
boolean
Default: true
Value: true

true (default): the current set, the only one served. false (history) was retired → 400.

source
Array of strings
Example: source=nws_wwa

Advisory source key(s) to read (nws_wwa, a customer advisory source key); repeat or comma-separate. Absent: every advisory source the caller reads — NWS while published, plus each customer advisory source it owns or is entitled to (a platform admin names others explicitly).

ugc
Array of strings
Example: ugc=NEC055

UGC zone code(s) (TXZ437, NEC055); repeat or comma-separate, case-insensitive. Matches an advisory that names any of them (customer polygons name none).

zip
Array of strings[ items^[0-9]{5}$ ]
Example: zip=68102

5-digit ZIP code(s) (Census 2020 ZCTA); repeat or comma-separate. Matches an advisory whose zcta lists any of them. An advisory whose ZIPs ingest has not computed yet (zcta_status null) never matches.

lat
number [ -90 .. 90 ]

With lon, advisories whose geometry (own polygon, else NWS zone shapes) covers this point.

lon
number [ -180 .. 180 ]

With lat.

Responses

Response samples

Content type
application/json
{
  • "as_of": "2019-08-24T14:15:22Z",
  • "active": true,
  • "types": [
    ]
}

List the active advisories from every provider

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

The active advisories from every provider the caller reads: NWS watches, warnings and advisories (nws_wwa, ingested from api.weather.gov every minute, while published) and the polygons of every customer advisory source (category advisory in /v1/observations/catalog) the caller owns or is entitled to. Each advisory names its source (key) and provider (NWS, or the customer source's owner handle). source narrows the set; a named customer source passes the same gate as /v1/observations/areas (404 hidden or unknown, 403 subscribe_required when listed and not subscribed), then must be an advisory source holding polygons (400 otherwise: an observation source is read through /v1/observations/*, whatever its shape).

NWS's set is exactly what NWS's /alerts/active returned at the last clean ingest poll: one entry per NWS alert id (a CAP segment, with its own ugc zones), Cancels and Updates included — message_type says which. A customer polygon is active while start ≤ now < end (an open end never expires) and takes the same shape: id is its obs_id; event, headline, description, severity, certainty, urgency, sender_name, instruction, area_desc, status and category come from its text attributes of the same name (null when absent); sent/effective/onset are its start and expires/ends its end; ugc, same, vtec and references are empty; values, units and attributes pass through.

Served whole (the national set is ~1–3 k) in one order across providers (sent newest first, then id); limit/offset are a safety valve and next_offset is set when a page was cut. History (active=false with since/until, paged by cursor) was retired: those parameters are refused with 400.

ZIP codes. Every advisory carries zcta, the Census 2020 ZCTA (ZIP) codes its footprint covers, computed once by ingest when it is written: from its polygon, else from the shapes of its NWS zones, else from its SAME counties (marine zones contribute none; overlaps under 0.5 % of a ZIP's area and under 0.5 km² are ignored). zcta_status and zcta_method say how (both null, with zcta: [], until ingest has computed them). zip filters on that list; GET /v1/zips shows what a ZIP code covers.

as_of is when ingest last polled NWS cleanly (customer sources have no poll clock): a consumer should treat an old as_of as an outage, not as "nothing new". With nothing to serve — NWS unpublished and no readable customer advisory source, or source=nws_wwa while NWS is unpublished — the answer is 404 advisories_unavailable, never an empty list.

The point filter (lat + lon) matches advisories whose geometry covers the point: their own polygon, else the union of their NWS zone shapes (geometry_source says which). An advisory with neither never matches a point.

Authorizations:
BearerAuth
query Parameters
active
boolean
Default: true
Value: true

true (default): the current set, the only one served. false (history) was retired → 400.

source
Array of strings
Example: source=nws_wwa

Advisory source key(s) to read (nws_wwa, a customer advisory source key); repeat or comma-separate. Absent: every advisory source the caller reads — NWS while published, plus each customer advisory source it owns or is entitled to (a platform admin names others explicitly).

event
Array of strings
Example: event=Tornado Warning

Event name(s); repeat the parameter or comma-separate. Any match.

ugc
Array of strings
Example: ugc=NEC055

UGC zone code(s) (TXZ437, NEC055); repeat or comma-separate, case-insensitive. Matches an advisory that names any of them (customer polygons name none).

zip
Array of strings[ items^[0-9]{5}$ ]
Example: zip=68102

5-digit ZIP code(s) (Census 2020 ZCTA); repeat or comma-separate. Matches an advisory whose zcta lists any of them. An advisory whose ZIPs ingest has not computed yet (zcta_status null) never matches.

lat
number [ -90 .. 90 ]

With lon, advisories whose geometry (own polygon, else NWS zone shapes) covers this point.

lon
number [ -180 .. 180 ]

With lat.

include
string
Value: "geometry"

geometry adds each advisory's GeoJSON MultiPolygon: its own polygon, else the union of its NWS zone shapes (geometry_source says which); null when it has neither. Omitted by default: polygons are large.

limit
integer [ 1 .. 10000 ]

Page size — default 5000, max 10000. Outside the range → 400 limit_out_of_range naming the cap.

offset
integer >= 0

The next_offset of the previous page.

Responses

Response samples

Content type
application/json
{
  • "as_of": "2019-08-24T14:15:22Z",
  • "active": true,
  • "count": 0,
  • "advisories": [
    ],
  • "next_offset": 0
}

Get one advisory, any provider

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

The advisory with this NWS id from the active set (active: true); else a readable customer polygon with this obs_id (active while its interval holds now; ingest prunes a polygon a day after it ends). source narrows the sources searched. An NWS advisory that has left the active set is gone: 404.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: urn:oid:2.49.0.1.840.0.0d3c4f1d2e3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c.001.1

The NWS alert id (NWS's own id for the message), or a customer polygon's obs_id; URL-encoded if needed.

query Parameters
include
string
Value: "geometry"

geometry adds each advisory's GeoJSON MultiPolygon: its own polygon, else the union of its NWS zone shapes (geometry_source says which); null when it has neither. Omitted by default: polygons are large.

source
Array of strings
Example: source=nws_wwa

Advisory source key(s) to read (nws_wwa, a customer advisory source key); repeat or comma-separate. Absent: every advisory source the caller reads — NWS while published, plus each customer advisory source it owns or is entitled to (a platform admin names others explicitly).

Responses

Response samples

Content type
application/json
{
  • "as_of": "2019-08-24T14:15:22Z",
  • "active": true,
  • "advisory": {
    }
}

What ZIP codes cover (NWS zones, counties, SAME codes)

Requires the read:observations scope. Visitors on the /demo-api alias are rate limited per client IP; keyed callers per key (429 with Retry-After).

For each 5-digit ZIP code (Census 2020 ZCTA): its state, a representative point inside it, the NWS forecast, fire and county zones it overlaps and its counties' SAME codes, from the reference vintage ingest computes advisory zcta lists with (vintage). Overlaps under 0.5 % of the ZIP's area and under 0.5 km² are ignored, the rule ingest applies to advisories, so the two agree. Marine zones never cover a ZIP. zips is sorted by zip; requested codes the vintage has no ZCTA for come back in unknown. Not metered.

Name the ZIPs with codes, or ask for every ZIP whose shape touches a box with bbox=west,south,east,north (one or the other, never both; unknown is [] for a box). A box is at most 4° a side and lists at most 400 ZIPs: more is 413 zips_too_many with count, so a map can say "zoom in".

include=geometry adds each ZIP's geometry (a GeoJSON MultiPolygon, simplified with ST_SimplifyPreserveTopology to simplify degrees, default 0.001 ≈ 100 m) and area_km2. The geometries of one answer are capped at 4 MB: over it is 413 zips_too_large — raise simplify or ask for fewer ZIPs.

Authorizations:
BearerAuth
query Parameters
codes
Array of strings [ 1 .. 200 ] items [ items^[0-9]{5}$ ]
Example: codes=68102&codes=02134

ZIP code(s); repeat or comma-separate; at most 200 after de-duplication. Required unless bbox is given.

bbox
string^-?[0-9.]+,-?[0-9.]+,-?[0-9.]+,-?[0-9.]+$
Example: bbox=-96.2,41.1,-95.8,41.4

west,south,east,north in degrees (west < east, south < north, each side at most 4°): every ZIP whose shape touches the box, at most 400 ZIPs (413 zips_too_many beyond). Instead of codes, never with it.

include
string
Value: "geometry"

geometry adds each ZIP's GeoJSON MultiPolygon (geometry) and its area_km2. Omitted by default: shapes are large.

simplify
number [ 0.0001 .. 0.01 ]
Default: 0.001
Example: simplify=0.001

With include=geometry, the ST_SimplifyPreserveTopology tolerance in degrees (0.0001 ≈ 10 m to 0.01 ≈ 1 km; default 0.001 ≈ 100 m). Checked, but without effect, without include=geometry.

Responses

Response samples

Content type
application/json
{
  • "vintage": {
    },
  • "zips": [
    ],
  • "unknown": [
    ]
}

mrms

MRMS radar point query

Returns every raw MRMS analysis frame within the requested [start, end) range, for a single point. MRMS is a radar analysis product (2-minute cadence) with no forecast run, so unlike other point-query endpoints there is no run field and no temporal interpolation — each returned frame is a raw reading. No server-side aggregation is performed (e.g. no max over the range); compute reductions client-side over the returned frames.

end must be after start, and the span between them may not exceed 24 hours.

A hole in coverage (a missed radar sweep, or a range that hasn't been ingested yet) is not an error — it just yields fewer frames than usual, including possibly zero.

Authorizations:
BearerAuth
Request Body schema: application/json
required
lat
required
number <float>

Latitude in degrees

lon
required
number <float>

Longitude in degrees

parameters
required
Array of strings

MRMS parameters to retrieve

start
required
string <date-time>

ISO 8601 start of the query range (inclusive).

end
required
string <date-time>

ISO 8601 end of the query range (exclusive). Must be after start, and the span between them may not exceed 24 hours.

Responses

Request samples

Content type
application/json
{
  • "lat": 35.2,
  • "lon": -97.4,
  • "parameters": [
    ],
  • "start": "2026-04-10T14:00:00Z",
  • "end": "2026-04-10T15:00:00Z"
}

Response samples

Content type
application/json
{
  • "model": "mrms",
  • "point": {
    },
  • "start": "2026-04-10T14:00:00Z",
  • "end": "2026-04-10T15:00:00Z",
  • "frames": [
    ]
}

verification

The model's headline Shyft Score

The composite Shyft Score for a model, and nothing else.

The measurements behind it are on /scorecard, which slices them by parameter, lead time, truth source, region, metric and window. The two endpoints answer different questions and deliberately do not overlap: this one is "how good is this model?", the other is "show me this slice". Serving the measurement list from both made them near-indistinguishable and cost a caller ~640 KB to render one number.

This endpoint takes no query parameters, and rejects any with a 400 rather than ignoring them — a filter accepted here and quietly dropped would return a 200 that reads as a filtered answer.

Always the rolling window. /scorecard is the endpoint that also answers month:YYYY-MM; the two are different questions and their numbers are not comparable.

shyft_score is absent when the engine has not stored a score for this model. That is "not scored yet", and it is distinct from an unknown model, which is a 404. The response still names methodology_version, so an absence says which methodology has nothing yet. Expect it for the first weeks after a deployment — the composite is anchored on a conditioned climatology that gains one observation per bucket per calendar day.

⚠ The event lane (spc_wind) is scorecard-only and never a composite input. Its measured skill is effectively zero — CSI 0.0003, with forecast centroids roughly 1,700 km from the storm reports it was scored against, because the forecast field is all-cause terrain gust rather than convective wind. It is served on /scorecard for completeness; do not present it as model skill.

Access. Verification scores are opt-in twice, and the two opt-ins are different decisions taken in order.

First, can_score — whether the model is measured at all. It is an entitlement granted to the producer, not something they set for themselves. A model that does not carry it has no score for anyone, including its own owner: there is nothing to show rather than something withheld. Unowned public_free models (every NOAA one) are measured by the platform and never carry the flag.

Second, score_published — whether the measured score is public. This one is the producer's own decision.

Publication cannot substitute for the entitlement: can_score is checked first, so setting score_published on a model that is not enabled still returns 404.

Condition Result
The model is unowned and public_free (every NOAA model) 200
Not can_score (and not an unowned free model) 404, before anything below
The caller belongs to the owning organization 200
The caller is the owning account 200
The producer has set score_published 200
Platform admin 200
Anything else 404

The denial is 404, not 403 — and it is the same 404 an unknown model returns. A 403 would confirm that the model exists and has scores, which is precisely what a producer who has not published is hiding.

Authenticated, but not metered — reading a verification score does not count as model-data usage.

Authorizations:
BearerAuth
path Parameters
model
required
string

Model slug (the public identifier; equals the name for platform models), e.g. hrrr.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "window_kind": "string",
  • "methodology_version": "1.4",
  • "composite_eligible_lanes": [
    ],
  • "shyft_score": {
    }
}

The model's Shyft Score month by month

The model's composite Shyft Score for each calendar month, oldest first — the series behind the number /score returns.

Why this endpoint exists. The rolling score row is upserted in place: each refresh overwrites the last, so October's number is gone by April and no history exists. The engine additionally writes one frozen row per calendar month, and this serves those.

A month seals on two conditions, not one: its seven-day lag has elapsed and the data behind it has stopped arriving. The second matters because data can land long after a month ends — a historical month can be measured for the first time years later — and sealing on the calendar alone would freeze whichever part of it happened to arrive first.

A sealed point does not move. It can still be completed if data for that month arrives that the engine did not have, which is rare after the lag and is the only thing that reopens it; a correction to an hour already counted cannot.

months is often empty, and that is a real answer. The series begins when the engine started writing monthly rows, not when the model started forecasting, and the composite additionally needs a climatology reference that began accumulating recently. Nothing is substituted for the absence.

provisional matters here more than anywhere else. A month inside its freeze lag can still move, and a month that pooled too few valid times is not reliable. A consumer must render those points differently rather than trending through them.

What a month-to-month difference means. The Shyft Score is skill against climatology (1 − mse_model/mse_clim), not absolute accuracy. A month whose weather is harder for climatology to predict raises the denominator, so a score can rise while the model's own error also rises. A seasonal reading of this series is a statement about skill relative to that season's climatology — not about which month the model was most accurate in.

This endpoint takes no query parameters and rejects any with a 400.

Access is the same gate as /score, in the same order — can_score first, then score_published — and the same 404 for both "no such model" and "not yours to read". See /score for the full matrix.

Authenticated, but not metered.

Authorizations:
BearerAuth
path Parameters
model
required
string

Model slug (the public identifier; equals the name for platform models), e.g. hrrr.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "methodology_version": "1.4",
  • "months": [
    ],
  • "unreadable": 0
}

The model's Shyft Score in each NOAA climate region

The model's rolling Shyft Score in each of the nine NOAA/NCEI U.S. climate regions (Karl, T. R., and W. J. Koss, 1984: Regional and National Monthly, Seasonal, and Annual Temperature Weighted by Area, 1895–1983. Historical Climatology Series 4-3, NCDC), in NCEI code order — 101 Northeast through 109 West.

Each region is scored on the same 0–100 scale against its own climatology; 50 means no better than climatology. Regional scores read the URMA and METAR lanes only — precipitation is not yet scored by region — so a regional number is a comparison view, not a piece of the headline. The headline on /score covers all of CONUS and is unchanged by regional scoring.

Pinned to the headline. Every region is read at the headline's own model version, methodology and window_end — the row /score serves — so one response never mixes versions, and a regional row the engine has stopped refreshing is never shown beside a live headline. No headline, no regions.

regions is often empty, and that is a real answer — no regional score stored yet, none at the headline's window, or the engine's regional table not created yet. A region with no points is absent rather than zero.

Rolling window only: there is no regional month-by-month series.

This endpoint takes no query parameters and rejects any with a 400.

Access is the same gate as /score, in the same order, with the same 404 for "no such model" and "not yours to read".

Authenticated, but not metered.

Authorizations:
BearerAuth
path Parameters
model
required
string

Model slug (the public identifier; equals the name for platform models), e.g. hrrr.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "window_kind": "rolling",
  • "methodology_version": "1.4",
  • "regions": [
    ],
  • "unreadable": 0
}

Models ranked for one calendar month

Every model the caller may see, ranked by Shyft Score for one calendar month, best first.

month is required. It is not defaulted to the current or latest month: a default would answer a different question with a 200, which is the defect the closed window vocabulary exists to prevent.

What this ranks, and what it does not. The Shyft Score is skill against climatology — 1 − mse_model/mse_clim — so this answers which model beat that month's climatology by most, not which model was most accurate. The two can diverge, and seasonally they are likely to: a more variable month is harder for climatology, which raises the denominator for everyone. reference travels on every entry so a consumer can see what each number is measured against, and two entries are only comparable when it matches.

⚠ This response carries no signal for whether two entrants are comparable, and you should not infer one. Models scored on different native grids cover different areas, and nothing here distinguishes them: reference is the same string (climatology) for every model under methodology 1.4 (as under every earlier one), and the stored score has no region at all. The nearest thing to a discriminator is lanes_used, and two models agreeing there still may not share a domain. Check each model's own /scorecard, which does carry region, before presenting a ranking as a fair fight.

Visibility. A producer's score is private until they publish it, and this is the only verification endpoint that returns a list of models — so it is the only one where that could leak. Each entrant is checked individually against the same rule the per-model endpoints use (can_score, then score_published); models the caller may not see are simply absent, and are not counted anywhere in the response, because a count would disclose that they exist.

incomplete. The flag that decides publication lives in the model catalog, not in this service's database. If that catalog cannot be reached for a model, the model is withheld — access fails closed — but the ranking is then short, and a silently short ranking is its own false statement ("this model was not among the best" when in truth it could not be checked). incomplete says so. It is a flag and not a count: under an outage every entrant is unanswerable whether or not it is published, so a count would be the month's private model population. A consumer should present the list as partial while this is true.

Authenticated, but not metered.

Authorizations:
BearerAuth
query Parameters
month
required
string^[1-9][0-9]{3}-(0[1-9]|1[0-2])$
Example: month=2026-10

Calendar month as YYYY-MM, zero-padded. Validated strictly: 2026-1, 2026-13, 26-10 and 2026-10-01 are all 400. Note the bare month — not the month: window-kind spelling /scorecard takes.

Responses

Response samples

Content type
application/json
{
  • "month": "2026-10",
  • "methodology_version": "1.4",
  • "models": [
    ],
  • "incomplete": true,
  • "unreadable": 0,
  • "truncated": true
}

The model's badges — where it beat every published rival

The slices on which this model has lower error than every published rival it was compared with, best first: overall, a season, all four seasons, a parameter group (alone or in one season), or a NOAA climate region. The engine compares two models on the Shyft Score components they share and writes, per slice, the mean log error ratio and its Bonferroni-corrected lower bound (the catalogue of 44 slices is the correction's size); this endpoint decides who counts and what is won.

A slice is won iff it has a comparison against at least one published rival and the lower bound is above zero against every published rival it has a comparison for. A rival with no comparison on a slice was not compared — never counted as beaten — and each badge's rivals lists exactly the rivals compared.

Rivals count by publication, not by caller. A rival counts iff its score is public (platform-owned free models, or a producer that is scored and published). An admin or an owner sees the same badges as a stranger, never names a private rival, and a private model never changes a public model's badges.

seasons:all is added when all four seasons are won, naming only the rivals compared in all four seasons (none in common: no seasons:all). The four season badges stay listed here (each id is stable); the grid's badge_count counts seasons:all once instead.

Versions. The subject's current version is chosen among its comparisons against published rivals, so a newer version compared only with a private model does not displace the public badges.

Order and headline. overall > seasons:all > season > group > group-in-season > region; within one, the larger worst-rival ratio first. headline is the first badge's id.

incomplete. If the catalog cannot say whether a rival is published, every badge that rival could change is withheld and incomplete is true. Retry shortly.

Only comparisons at the newest methodology are read, and only the subject's and each rival's current version. badges is often empty, and that is a real answer — no rival, nothing won, or the engine's table not created yet.

This endpoint takes no query parameters and rejects any with a 400. Access to the subject is the same gate as /score, with the same 404. Authenticated, but not metered.

Authorizations:
BearerAuth
path Parameters
model
required
string

Model slug, e.g. hrrr.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "model_version": "string",
  • "methodology_version": "1.4",
  • "headline": "overall",
  • "badges": [
    ],
  • "incomplete": true
}

Every visible model's headline badge

For a catalogue grid: each model the caller may see that holds at least one badge, with its headline badge and how many it holds — one request instead of one per card. The badges are decided exactly as on /v1/verification/models/{model}/badges.

Each model is checked against the same visibility rule as the per-model endpoints; a model the caller may not see is absent and not counted. A model (or a rival) whose status the catalog cannot answer is withheld and incomplete is true — a flag, not a count, as on the month ranking.

Takes no query parameters. Authenticated, but not metered.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "methodology_version": "1.4",
  • "models": [
    ],
  • "incomplete": true
}

Verification scorecard for a slice

The same per-parameter, per-lead-time entries as /score, narrowed to a slice: by parameter, lead time, truth source, region, metric, aggregate window and model version. This is the auditable table behind a score.

The "Severe Weather Skill" panel is truth_source=spc_wind. It is a slice of this endpoint, never a composite input — see the caveat below.

Metric names are the engine's, not translated. me is mean error (commonly called bias) and gss is the Gilbert Skill Score (equivalent to ETS). A metric named differently here than in the engine's own output would be a number nobody could trace, so the names are served verbatim and the equivalences documented instead.

Two windows, two different questions. rolling pools the last N days and moves; month:YYYY-MM covers one calendar month's valid times only and seals once its seven-day lag has elapsed and its data has stopped arriving. They are not comparable, which is why window is validated strictly rather than falling back to a default. There is no all-time window: a number that averaged across model upgrades would describe no model that runs today, so lifetime is a 400 like any other unknown value.

Unknown filter values and unknown filter keys behave differently, on purpose. An unrecognised value (parameter=not_a_parameter) is a legitimate question with an empty answer: 200 and an empty entries. An unrecognised key (paramter=temperature_2m) is 400 — it is a filter the caller believes is applied and is not, and silently ignoring it would return the whole table as though it were a filtered slice.

applied_filters echoes what was actually applied, and truncated says whether the slice hit the row ceiling. Both exist so a caller never has to assume the response is the slice they asked for.

⚠ The event lane (spc_wind) is scorecard-only and never a composite input. Its measured skill is effectively zero — CSI 0.0003, with forecast centroids roughly 1,700 km from the storm reports it was scored against, because the forecast field is all-cause terrain gust rather than convective wind. It is served for completeness; do not present it as model skill.

Access. Verification scores are opt-in. A caller may read a model's scores when any of these holds:

Condition Result
The model is unowned and public_free (every NOAA model) 200
The caller belongs to the owning organization 200
The producer has set score_published 200
Platform admin 200
Anything else 404

The denial is 404, not 403 — and it is the same 404 an unknown model returns. A 403 would confirm that the model exists and has scores, which is precisely what a producer who has not published is hiding.

Authenticated, but not metered — reading verification scores does not count as model-data usage.

Authorizations:
BearerAuth
path Parameters
model
required
string

Model slug (the public identifier; equals the name for platform models), e.g. hrrr.

query Parameters
parameter
string

Exact match, e.g. temperature_2m.

lead
integer

Exact match on lead_time_hours. lead=0 is the analysis hour and is a real filter, not an absent one.

truth_source
string

Exact match, e.g. urma. truth_source=spc_wind is the Severe Weather Skill slice.

region
string

Exact match, e.g. conus. Lanes do not all cover the same area, so entries are only comparable within a region. Without it, precipitation (mrms_qpe) is served on the common 0.25° grid conus_0p25 — the comparable rows the Shyft Score reads — when the model, and the requested slice, is scored there. Keys scored only on the per-model grid are available with region=conus. applied_filters.default_regions names what was defaulted. The station lane (metar_surface) is never defaulted: it is served over both its regions, conus (the stations the Shyft Score reads) and model_domain (every station in the model's grid), as distinct rows.

NOAA climate regions. The nine NCEI U.S. climate regions (Karl and Koss, 1984) are scored as comparison rows for the URMA and METAR lanes: ncei_northeast (101), ncei_upper_midwest (102), ncei_ohio_valley (103), ncei_southeast (104), ncei_northern_rockies_plains (105), ncei_south (106), ncei_southwest (107), ncei_northwest (108), ncei_west (109). They are excluded unless asked for: without region the card is the all-CONUS view it always was; region=ncei_southeast returns that region's rows. The ncei_ namespace is closed — any other ncei_* value is a 400 naming the nine. On an unfiltered card available.regions omits the ncei_* slugs too; available.region_names carries each one's slug and display name.

metric
string

Exact match, e.g. rmse, me, csi, gss, msess.

window
string^(rolling|month:[1-9][0-9]{3}-(0[1-9]|1[0-2])...
Default: "rolling"
Example: window=rolling

Validated against the pattern above — any other value is 400, and that strictness is load-bearing: every accepted window returns plausible data, so a typo that fell through to the default would hand back a different question's answer with a 200.

Two kinds. rolling is the last verdandi_window_days. month:YYYY-MM is one calendar month, computed over that month's valid times only, sealed once its seven-day lag has elapsed and its data has stopped arriving. The retired lifetime window is a 400.

The two are not comparable with each other — different spans, different questions.

version
string

Exact match on model_version. Only meaningful for versioned models; every NOAA model is unversioned.

limit
integer [ 1 .. 5000 ]
Default: 5000

Row ceiling, not a page size — there is no cursor. When the ceiling is reached the response sets truncated; narrow the filters.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "window_kind": "string",
  • "composite_eligible_lanes": [
    ],
  • "applied_filters": {
    },
  • "truncated": true,
  • "available": {
    },
  • "entries": [
    ]
}