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.
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.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.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.
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.
{- "status": "healthy",
- "loaded_models": [
- "gfs",
- "hrrr"
], - "degraded_models": [
- {
- "model": "mrms",
- "error": "read coordinate data /mrms/latitude: object not found",
- "since": "2026-07-23T13:00:00Z"
}
], - "snapshot_id": "abc123",
- "last_reload": "2026-03-04T00:15:30Z",
- "snapshot_committed_at": "2026-03-04T00:15:12Z",
- "models": {
- "property1": {
- "snapshot_id": "1CECHNKREP0SNAP5H0T1D",
- "committed_at": "2026-10-14T13:00:12Z"
}, - "property2": {
- "snapshot_id": "1CECHNKREP0SNAP5H0T1D",
- "committed_at": "2026-10-14T13:00:12Z"
}
}, - "repos_walked": true,
- "build": {
- "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"
}
}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.
{- "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"
}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.
{- "outcome": "reloaded",
- "generation": 1,
- "error": "string"
}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.
{- "status": "reloaded",
- "snapshot_id": "def456",
- "models_loaded": [
- "gfs",
- "hrrr"
], - "duration_ms": 1250
}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.
| model required | string Example: hrrr Model slug (the public identifier; equals the name for platform models). |
{- "status": "reloaded",
- "snapshot_id": "def456",
- "models_loaded": [
- "gfs",
- "hrrr"
], - "duration_ms": 1250
}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.
{- "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": {
- "chunk": {
- "bytes": 5368709120,
- "entries": 48291,
- "hits": 1847293,
- "misses": 4521,
- "prefetches": 8134,
- "prewarms": 192044,
- "evictions": 312,
- "explicit_removals": 96
}, - "tile": {
- "bytes": 5368709120,
- "entries": 48291,
- "hits": 1847293,
- "misses": 4521,
- "prefetches": 8134,
- "prewarms": 192044,
- "evictions": 312,
- "explicit_removals": 96
}, - "lattice": {
- "bytes": 5368709120,
- "entries": 48291,
- "hits": 1847293,
- "misses": 4521,
- "prefetches": 8134,
- "prewarms": 192044,
- "evictions": 312,
- "explicit_removals": 96
}, - "past_run": {
- "bytes": 5368709120,
- "entries": 48291,
- "hits": 1847293,
- "misses": 4521,
- "prefetches": 8134,
- "prewarms": 192044,
- "evictions": 312,
- "explicit_removals": 96
}
}, - "prewarm": {
- "in_flight": true,
- "enabled": true,
- "last_cycle": {
- "model_count": 2,
- "chunks_loaded": 8640,
- "chunks_skipped": 120,
- "models_errored": 0,
- "duration_ms": 41250,
- "finished_at": "2019-08-24T14:15:22Z",
- "plan_full_bytes": 5211340800,
- "plan_kept_bytes": 1995840000,
- "trimmed": true
}
}
}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.
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "models": [
- {
- "slug": "gfs",
- "name": "gfs",
- "owner": {
- "kind": "platform",
- "id": null
}, - "latest_run": "2026-03-04T12Z",
- "grid_type": "regular",
- "bounds": {
- "lat_min": -90,
- "lat_max": 90,
- "lon_min": -180,
- "lon_max": 180
}, - "parameters": [
- "temperature_surface",
- "wind_speed_gust_surface"
], - "status": "ready",
- "layout": "forecast",
- "is_customer": false,
- "producer": "NOAA"
}
]
}Returns available parameters for a specific model, including metadata like units and available forecast steps.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "model": "gfs",
- "run_time": "2026-03-04T12:00:00Z",
- "parameters": [
- {
- "name": "t",
- "long_name": "Temperature",
- "units": "K",
- "steps": [
- 0,
- 3,
- 6,
- 9,
- 12
], - "shape": [
- 721,
- 1440
]
}
]
}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.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "model": "gfs",
- "run_time": "2026-03-04T12:00:00Z",
- "steps": [
- 0,
- 3,
- 6,
- 9,
- 12,
- 15,
- 18,
- 21,
- 24
], - "status": "ready",
- "ingesting_run": {
- "run_time": "2026-10-03T19:00:00Z",
- "steps": [
- 0,
- 1,
- 2,
- 3,
- 4,
- 5,
- 6,
- 7,
- 8,
- 9
], - "declared_steps": 19
}
}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.
| model required | string Example: mrms Model slug (the public identifier; equals the name for platform models). |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "model": "mrms",
- "layout": "analysis",
- "times": [
- "2026-03-04T12:00:00+00:00",
- "2026-03-04T12:02:00+00:00"
], - "count": 2,
- "status": "ready"
}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.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "model": "gfs",
- "loaded_run": "2026-03-04T12Z",
- "runs": [
- {
- "name": "2026-03-04T12Z",
- "has_coordinates": true,
- "has_variables": true,
- "step_count": 19,
- "steps": [
- 0,
- 1,
- 2,
- 3,
- 4,
- 5,
- 6,
- 7,
- 8,
- 9,
- 10,
- 11,
- 12,
- 13,
- 14,
- 15,
- 16,
- 17,
- 18
]
}
]
}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.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
| 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. |
{- "lat": 40.7,
- "lon": -73.9,
- "parameters": [
- "temperature_surface",
- "wind_speed_gust_surface"
], - "datetime": "2026-03-04T18:00:00Z",
- "run": "2026-03-04T12:00:00Z"
}{- "model": "gfs",
- "run_time": "2026-03-04T12:00:00Z",
- "point": {
- "lat": 40.7,
- "lon": -73.9
}, - "valid_time": "2026-03-04T18:00:00Z",
- "values": {
- "t": {
- "value": 275.3,
- "units": "K"
}, - "gust": {
- "value": 5.2,
- "units": "m/s"
}
}
}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.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
| 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). |
{- "lat": 40.7,
- "lon": -73.9,
- "parameters": [
- "temperature_surface"
], - "datetimes": [
- "2026-03-04T18:00:00Z",
- "2026-03-04T21:00:00Z"
], - "run": "2026-03-04T12:00:00Z"
}{- "model": "gfs",
- "run_time": "2026-03-04T12:00:00Z",
- "point": {
- "lat": 40.7,
- "lon": -73.9
}, - "series": [
- {
- "valid_time": "2026-03-04T18:00:00Z",
- "values": {
- "property1": {
- "value": 275.3,
- "units": "K"
}, - "property2": {
- "value": 275.3,
- "units": "K"
}
}, - "gap": true
}
]
}Returns interpolated weather values along a series of waypoints, each with its own datetime. Temporal interpolation is applied at each waypoint independently.
| model required | string Example: gfs Model slug (the public identifier; equals the name for platform models). |
required | Array of objects (Waypoint) |
| parameters required | Array of strings |
| run | string <date-time> Optional model run to query (ISO 8601). |
{- "waypoints": [
- {
- "lat": 40.7,
- "lon": -73.9,
- "datetime": "2026-03-04T18:00:00Z"
}
], - "parameters": [
- "temperature_surface",
- "wind_speed_gust_surface"
], - "run": "2026-03-04T12:00:00Z"
}{- "model": "gfs",
- "run_time": "2026-03-04T12:00:00Z",
- "waypoints": [
- {
- "point": {
- "lat": 40.7,
- "lon": -73.9
}, - "valid_time": "2026-03-04T18:00:00Z",
- "values": {
- "property1": {
- "value": 275.3,
- "units": "K"
}, - "property2": {
- "value": 275.3,
- "units": "K"
}
}
}
]
}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.
| model required | string Example: hrrr Model slug (the public identifier; equals the name for platform models). |
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). |
{- "bounds": {
- "north": 42,
- "south": 38,
- "east": -72,
- "west": -78
}, - "width": 128,
- "height": 128,
- "parameters": [
- "temperature_surface"
], - "datetime": "2026-03-04T18:00:00Z",
- "run": "2026-03-04T12:00:00Z"
}{- "model": "hrrr",
- "run_time": "2026-03-04T12:00:00Z",
- "valid_time": "2026-03-04T18:00:00Z",
- "bounds": {
- "north": 42,
- "south": 38,
- "east": -72,
- "west": -78
}, - "width": 128,
- "height": 128,
- "grids": {
- "temperature_surface": {
- "values": [
- 280,
- 281,
- 282,
- 283
], - "units": "K"
}
}
}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)
| 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 |
{- "lat": 35.2,
- "lon": -97.4,
- "datetime": "2026-03-04T18:00:00Z",
- "run": "2026-03-04T12:00:00Z",
- "threshold": 1.5
}{- "model": "hrrr_diagnostic",
- "run_time": "2026-03-04T12:00:00Z",
- "point": {
- "lat": 40.7,
- "lon": -73.9
}, - "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
}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).
| 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) |
| 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 |
| encoding | string Default: "grey8" Enum: "grey8" "rg16" Pixel encoding: |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "error": "model_not_found",
- "message": "model not found: xyz"
}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.
| model required | string Example: hrrr Model slug (the public identifier; equals the name for platform models). |
| parameter required | string Example: temperature_surface |
| If-None-Match | string Example: W/"3f2a9c0d8e7b6a5f4e3d2c1b0a998877" The |
{- "model": "hrrr",
- "parameter": "temperature_surface",
- "min_value": 200,
- "max_value": 330,
- "units": "K",
- "steps": [
- 0,
- 1,
- 2,
- 3
], - "encoding": "grey8",
- "encodings": [
- "grey8",
- "rg16"
], - "levels": {
- "grey8": 255,
- "rg16": 65535
}, - "range_source": "attr"
}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.
| 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. |
{- "center_time": "2026-06-01T18:00:00Z"
}{- "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"
}Returns the job's current status and progress, proxied from
wxchange-ingest. status progresses pending → discovering →
ingesting → ready (or failed).
| job_id required | string <uuid> Example: 3f2a9e1c-9d3b-4b7a-9c1a-8e6f1a2b3c4d The |
{- "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"
}Point-observation data (SPC/NCEI storm reports) — a separate PostGIS store, not the Zarr forecast/analysis models
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.
{- "sources": [
- {
- "source": "spc",
- "earliest": "2019-08-24T14:15:22Z",
- "latest": "2019-08-24T14:15:22Z",
- "row_count": 0,
- "name": "string",
- "kind": "points",
- "category": "observation",
- "owner": true,
- "units": {
- "property1": "string",
- "property2": "string"
}
}
]
}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.
| bbox required | string Example: bbox=-125,24,-66,50
|
| source | string Example: source=madis_metar Restrict to one source key (e.g. |
| start | string <date-time> Defaults to 24 hours before |
| end | string <date-time> Defaults to now. |
| cursor | string Opaque keyset cursor from a previous response's |
| limit | integer [ 1 .. 2000 ] Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "madis:metar:KMCI:1700000000",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.34,
- 35.51
]
}, - "properties": {
- "observed_at": "2026-07-16T21:00:00Z",
- "source": "madis_metar",
- "station_id": "KMCI",
- "station_name": "Kansas City International Airport",
- "station_state": "MO",
- "station_country": "US",
- "temperature_c": 22.5,
- "wind_speed_ms": 5,
- "raw_metar": "KMCI 162100Z 18010KT 10SM CLR 23/14 A3005"
}
}
], - "next_cursor": "string"
}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.
| source | string Example: source=madis_metar Restrict to one source key (e.g. |
| bbox | string Example: bbox=-125,24,-66,50 Optional |
| limit | integer [ 1 .. 2000 ] Max stations. Default 500, max 2000; a value outside 1..2000 is refused with 400 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "KMCI",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.34,
- 35.51
]
}, - "properties": {
- "source": "madis_metar",
- "station_id": "KMCI",
- "name": "Kansas City Intl",
- "state": "MO",
- "country": "US",
- "elevation_m": 312
}
}
]
}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.
| station_id required | string Example: KMCI |
| source | string Example: source=madis_metar Restrict to one source key. Omit to search all published sources for the station. A customer source key ( |
| start | string <date-time> Defaults to 24 hours before |
| 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 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "madis:metar:KMCI:1700000000",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.34,
- 35.51
]
}, - "properties": {
- "observed_at": "2026-07-16T21:00:00Z",
- "source": "madis_metar",
- "station_id": "KMCI",
- "station_name": "Kansas City International Airport",
- "station_state": "MO",
- "station_country": "US",
- "temperature_c": 22.5,
- "wind_speed_ms": 5,
- "raw_metar": "KMCI 162100Z 18010KT 10SM CLR 23/14 A3005"
}
}
], - "next_cursor": "string"
}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.
| 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 ( |
| 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 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "madis:metar:KMCI:1700000000",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.34,
- 35.51
]
}, - "properties": {
- "observed_at": "2026-07-16T21:00:00Z",
- "source": "madis_metar",
- "station_id": "KMCI",
- "station_name": "Kansas City International Airport",
- "station_state": "MO",
- "station_country": "US",
- "temperature_c": 22.5,
- "wind_speed_ms": 5,
- "raw_metar": "KMCI 162100Z 18010KT 10SM CLR 23/14 A3005"
}
}
], - "next_cursor": "string"
}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.
| 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
|
| start | string <date-time> Defaults to 24 hours before |
| end | string <date-time> Defaults to now. |
| cursor | string Opaque keyset cursor from a previous response's |
| limit | integer [ 1 .. 1000 ] Page size. Default 100, max 1000; a value outside 1..1000 is refused with 400 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "string",
- "geometry": { },
- "properties": {
- "source": "string",
- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
- "values": { },
- "attributes": {
- "property1": "string",
- "property2": "string"
}, - "units": {
- "property1": "string",
- "property2": "string"
}
}
}
], - "next_cursor": "string"
}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.
| bbox required | string Example: bbox=-98.5,34.0,-96.0,36.5
|
| start | string <date-time> Example: start=2026-06-01T00:00:00Z Defaults to 24 hours before |
| 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. |
| cursor | string Opaque keyset cursor from a previous response's |
| limit | integer [ 1 .. 2000 ] Page size. Default 500, max 2000; a value outside 1..2000 is refused with 400 |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "id": "spc:hail:9d1f...c3",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.51,
- 35.47
]
}, - "properties": {
- "observed_at": "2026-06-01T21:14:00Z",
- "source": "spc_storm_reports",
- "report_type": "hail",
- "size_inches": 1.75,
- "state": "OK",
- "county": "OKLAHOMA",
- "comments": "Hail up to golf ball size reported near Moore."
}
}, - {
- "type": "Feature",
- "id": "ncei:1234567",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -98.02,
- 34.61
]
}, - "properties": {
- "observed_at": "2011-05-24T20:55:00Z",
- "source": "ncei_storm_events",
- "report_type": "tornado",
- "f_scale": 4,
- "state": "OK",
- "state_fips": "40",
- "cz_fips": "051",
- "county": "GRADY",
- "event_narrative": "Long-track violent tornado."
}
}
], - "next_cursor": null
}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.
{- "sources": [
- {
- "source": "spc",
- "earliest": "2019-08-24T14:15:22Z",
- "latest": "2019-08-24T14:15:22Z",
- "row_count": 0,
- "name": "string",
- "kind": "points",
- "category": "observation",
- "owner": true,
- "units": {
- "property1": "string",
- "property2": "string"
}
}
], - "report_types": [
- "hail",
- "wind",
- "tornado"
]
}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.
| bbox required | string Example: bbox=-103.0,33.5,-94.0,37.0
|
| start | string <date-time> Example: start=2024-01-01T00:00:00Z Defaults to 2 years before |
| 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 ( |
| 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 |
{- "counties": [
- {
- "fips": "40051",
- "county": "GRADY",
- "state": "OK",
- "total": 37,
- "by_year": {
- "2011": 5,
- "2013": 2
}
}
]
}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.
| obs_id required | string Example: spc:hail:9f3ac21d4b7e |
{- "type": "Feature",
- "id": "madis:metar:KMCI:1700000000",
- "geometry": {
- "type": "Point",
- "coordinates": [
- -97.34,
- 35.51
]
}, - "properties": {
- "observed_at": "2026-07-16T21:00:00Z",
- "source": "madis_metar",
- "station_id": "KMCI",
- "station_name": "Kansas City International Airport",
- "station_state": "MO",
- "station_country": "US",
- "temperature_c": 22.5,
- "wind_speed_ms": 5,
- "raw_metar": "KMCI 162100Z 18010KT 10SM CLR 23/14 A3005"
}
}NWS watches, warnings and advisories plus customer advisory sources — the current set, from the observation store — and the ZIP code lookup
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.
| active | boolean Default: true Value: true
|
| source | Array of strings Example: source=nws_wwa Advisory source key(s) to read ( |
| ugc | Array of strings Example: ugc=NEC055 UGC zone code(s) ( |
| 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 |
| lat | number [ -90 .. 90 ] With |
| lon | number [ -180 .. 180 ] With |
{- "as_of": "2019-08-24T14:15:22Z",
- "active": true,
- "types": [
- {
- "event": "string",
- "count": 0
}
]
}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.
| active | boolean Default: true Value: true
|
| source | Array of strings Example: source=nws_wwa Advisory source key(s) to read ( |
| 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) ( |
| 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 |
| lat | number [ -90 .. 90 ] With |
| lon | number [ -180 .. 180 ] With |
| include | string Value: "geometry"
|
| limit | integer [ 1 .. 10000 ] Page size — default 5000, max 10000. Outside the range → 400 |
| offset | integer >= 0 The |
{- "as_of": "2019-08-24T14:15:22Z",
- "active": true,
- "count": 0,
- "advisories": [
- {
- "id": "string",
- "source": "nws_wwa",
- "provider": "NWS",
- "url": "string",
- "event": "Tornado Warning",
- "severity": "string",
- "certainty": "string",
- "urgency": "string",
- "status": "string",
- "message_type": "string",
- "category": "string",
- "headline": "string",
- "description": "string",
- "instruction": "string",
- "area_desc": "string",
- "sender_name": "string",
- "web": "string",
- "ugc": [
- "string"
], - "same": [
- "string"
], - "vtec": [
- "string"
], - "references": [
- "string"
], - "sent": "2019-08-24T14:15:22Z",
- "effective": "2019-08-24T14:15:22Z",
- "onset": "2019-08-24T14:15:22Z",
- "expires": "2019-08-24T14:15:22Z",
- "ends": "2019-08-24T14:15:22Z",
- "zcta": [
- "68102",
- "68104"
], - "zcta_status": "ok",
- "zcta_method": "polygon",
- "geometry_source": "polygon",
- "geometry": { },
- "values": { },
- "units": {
- "property1": "string",
- "property2": "string"
}, - "attributes": {
- "property1": "string",
- "property2": "string"
}
}
], - "next_offset": 0
}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.
| 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 |
| include | string Value: "geometry"
|
| source | Array of strings Example: source=nws_wwa Advisory source key(s) to read ( |
{- "as_of": "2019-08-24T14:15:22Z",
- "active": true,
- "advisory": {
- "id": "string",
- "source": "nws_wwa",
- "provider": "NWS",
- "url": "string",
- "event": "Tornado Warning",
- "severity": "string",
- "certainty": "string",
- "urgency": "string",
- "status": "string",
- "message_type": "string",
- "category": "string",
- "headline": "string",
- "description": "string",
- "instruction": "string",
- "area_desc": "string",
- "sender_name": "string",
- "web": "string",
- "ugc": [
- "string"
], - "same": [
- "string"
], - "vtec": [
- "string"
], - "references": [
- "string"
], - "sent": "2019-08-24T14:15:22Z",
- "effective": "2019-08-24T14:15:22Z",
- "onset": "2019-08-24T14:15:22Z",
- "expires": "2019-08-24T14:15:22Z",
- "ends": "2019-08-24T14:15:22Z",
- "zcta": [
- "68102",
- "68104"
], - "zcta_status": "ok",
- "zcta_method": "polygon",
- "geometry_source": "polygon",
- "geometry": { },
- "values": { },
- "units": {
- "property1": "string",
- "property2": "string"
}, - "attributes": {
- "property1": "string",
- "property2": "string"
}
}
}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.
| 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 | string^-?[0-9.]+,-?[0-9.]+,-?[0-9.]+,-?[0-9.]+$ Example: bbox=-96.2,41.1,-95.8,41.4
|
| include | string Value: "geometry"
|
| simplify | number [ 0.0001 .. 0.01 ] Default: 0.001 Example: simplify=0.001 With |
{- "vintage": {
- "id": 3,
- "label": "zcta520-nws18mr25",
- "nws_release": "18mr25"
}, - "zips": [
- {
- "zip": "68102",
- "state": "NE",
- "lat": 0,
- "lon": 0,
- "zones": [
- {
- "ugc": "NEZ052",
- "type": "forecast",
- "name": "Douglas"
}
], - "same": [
- "031055"
], - "area_km2": 12.346,
- "geometry": { }
}
], - "unknown": [
- "99999"
]
}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.
| 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
|
{- "lat": 35.2,
- "lon": -97.4,
- "parameters": [
- "merged_reflectivity_qc_composite_500m_amsl",
- "vil_500m_amsl"
], - "start": "2026-04-10T14:00:00Z",
- "end": "2026-04-10T15:00:00Z"
}{- "model": "mrms",
- "point": {
- "lat": 40.7,
- "lon": -73.9
}, - "start": "2026-04-10T14:00:00Z",
- "end": "2026-04-10T15:00:00Z",
- "frames": [
- {
- "valid_time": "2026-04-10T14:02:00Z",
- "values": {
- "property1": {
- "value": 275.3,
- "units": "K"
}, - "property2": {
- "value": 275.3,
- "units": "K"
}
}
}
]
}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/scorecardfor 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.
| model required | string Model slug (the public identifier; equals the name for platform models), e.g. |
{- "model": "string",
- "window_kind": "string",
- "methodology_version": "1.4",
- "composite_eligible_lanes": [
- "string"
], - "shyft_score": {
- "value": 0.1,
- "ci_lower": 0.1,
- "ci_upper": 0.1,
- "reference": "climatology",
- "methodology_version": "1.4",
- "model_version": "v2",
- "lanes_used": [
- "string"
], - "n_components": 0,
- "provisional": true,
- "window_end": "2019-08-24T14:15:22Z"
}
}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.
| model required | string Model slug (the public identifier; equals the name for platform models), e.g. |
{- "model": "string",
- "methodology_version": "1.4",
- "months": [
- {
- "month": "2026-10",
- "value": 0.1,
- "ci_lower": 0.1,
- "ci_upper": 0.1,
- "reference": "climatology",
- "methodology_version": "string",
- "model_version": "string",
- "lanes_used": [
- "string"
], - "n_components": 0,
- "provisional": true,
- "window_start": "2019-08-24T14:15:22Z",
- "window_end": "2019-08-24T14:15:22Z",
- "provenance": "archive"
}
], - "unreadable": 0
}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.
| model required | string Model slug (the public identifier; equals the name for platform models), e.g. |
{- "model": "string",
- "window_kind": "rolling",
- "methodology_version": "1.4",
- "regions": [
- {
- "region": "ncei_northeast",
- "code": 101,
- "name": "Southeast",
- "value": 0,
- "ci_lower": 0,
- "ci_upper": 0,
- "reference": "string",
- "methodology_version": "string",
- "model_version": "string",
- "lanes_used": [
- "string"
], - "n_components": 0,
- "provisional": true,
- "window_end": "2019-08-24T14:15:22Z"
}
], - "unreadable": 0
}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:
referenceis 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 islanes_used, and two models agreeing there still may not share a domain. Check each model's own/scorecard, which does carryregion, 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.
| month required | string^[1-9][0-9]{3}-(0[1-9]|1[0-2])$ Example: month=2026-10 Calendar month as |
{- "month": "2026-10",
- "methodology_version": "1.4",
- "models": [
- {
- "model": "string",
- "value": 0.1,
- "ci_lower": 0.1,
- "ci_upper": 0.1,
- "reference": "climatology",
- "methodology_version": "string",
- "model_version": "string",
- "lanes_used": [
- "string"
], - "n_components": 0,
- "provisional": true,
- "provenance": "archive"
}
], - "incomplete": true,
- "unreadable": 0,
- "truncated": true
}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.
| model required | string Model slug, e.g. |
{- "model": "string",
- "model_version": "string",
- "methodology_version": "1.4",
- "headline": "overall",
- "badges": [
- {
- "id": "season:summer",
- "family": "overall",
- "label_key": "season.summer",
- "window": "months",
- "rivals": [
- {
- "model": "gfs",
- "n": 0,
- "ratio": 1.39
}
], - "first_month": "2021-01",
- "last_month": "2026-09"
}
], - "incomplete": true
}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.
{- "methodology_version": "1.4",
- "models": [
- {
- "model": "string",
- "headline": {
- "id": "season:summer",
- "family": "overall",
- "label_key": "season.summer",
- "window": "months",
- "rivals": [
- {
- "model": "gfs",
- "n": 0,
- "ratio": 1.39
}
], - "first_month": "2021-01",
- "last_month": "2026-09"
}, - "badge_count": 1
}
], - "incomplete": true
}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.
| model required | string Model slug (the public identifier; equals the name for platform models), e.g. |
| parameter | string Exact match, e.g. |
| lead | integer Exact match on |
| truth_source | string Exact match, e.g. |
| region | string Exact match, e.g. 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: |
| metric | string Exact match, e.g. |
| 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. The two are not comparable with each other — different spans, different questions. |
| version | string Exact match on |
| limit | integer [ 1 .. 5000 ] Default: 5000 Row ceiling, not a page size — there is no cursor. When the ceiling
is reached the response sets |
{- "model": "string",
- "window_kind": "string",
- "composite_eligible_lanes": [
- "string"
], - "applied_filters": {
- "parameter": "string",
- "lead": 0,
- "truth_source": "string",
- "region": "string",
- "metric": "string",
- "version": "string",
- "default_regions": {
- "property1": "string",
- "property2": "string"
}
}, - "truncated": true,
- "available": {
- "parameters": [
- "string"
], - "lead_times": [
- 0
], - "truth_sources": [
- "string"
], - "regions": [
- "string"
], - "metrics": [
- "string"
], - "versions": [
- "string"
], - "region_names": {
- "property1": "string",
- "property2": "string"
}
}, - "entries": [
- {
- "truth_source": "string",
- "model_version": "string",
- "parameter": "string",
- "lead_time_hours": 0,
- "region": "string",
- "metric": "string",
- "metric_qualifier": "string",
- "baseline_model": "string",
- "value": 0,
- "ci_lower": 0,
- "ci_upper": 0,
- "n_valid_times": 0,
- "n_samples_total": 0,
- "provisional": true,
- "methodology_version": "string",
- "window_start": "2019-08-24T14:15:22Z",
- "window_end": "2019-08-24T14:15:22Z"
}
]
}