# Snowpack Context

> Compare a station's snowpack with its own WY1991–2020 history: 24 h and 72 h change, percent of median, percentile and rank, a water year against its band, and stations ranked by gain or anomaly.

Snowpack Context is what Open SNOTEL derives from the observations: how much a station's snowpack changed recently, how today compares with the same day in the station's own history, whether an accumulation event is underway, and which stations stand out right now. Three endpoints serve it:

| Method and path                              | Answers                                                            |
| -------------------------------------------- | ------------------------------------------------------------------ |
| `GET /api/v1/stations/{station}/context`     | How much snow is here, what changed, and how unusual is it?        |
| `GET /api/v1/stations/{station}/climatology` | How is this water year tracking against the station's history?     |
| `GET /api/v1/rankings`                       | Where are the largest gains, the deepest or most unusual snowpack? |

All three read state Open SNOTEL has already computed; nothing is derived during a request. Derived values are recomputed hourly after new observations arrive, so a response is at most about an hour behind the readings.

## What the numbers mean

- **Observed or derived.** Every value carries `category`. `observed` came straight from SNOTEL. `derived` was computed from observed values by a versioned derivation, named in `derivation` (`id` and `version`); a new version can change a derived number while the observations stay exactly as they were.
- **Percent of median.** Today's value as a percent of the station's median for the same day of the water year over the baseline years. It is computed by Open SNOTEL from the station's own history, not an official NRCS "percent of normal". When the median is 0 (early or late season) it is unavailable with `zero_median`; the percentile and rank may still be there.
- **Historical percentile and rank.** Where today's value falls among the baseline years' values on this day: the percentile counts years below (ties count half), and rank 1 is the highest, `of` the baseline years plus today. A percentile is not a percent of median: 72nd percentile and 118% of median are different statements.
- **Baseline.** `baseline` names the water years compared against: WY1991–2020. The current water year is left out. A station installed later has fewer years; a day with fewer than ten has `insufficient_samples` and no number. February 29 is its own day and usually has too few years; it is never borrowed from February 28.
- **Changes.** `change24h` and `change72h` are signed differences between two readings of one sensor, named in `start` and `end`. A change in snow depth is not snowfall: settlement, melt and drifting move it too.
- **Accumulation events.** A run of days on which the snow water equivalent sensor gained, with what was measured during it (`sweGain`, `snowDepthChange`, `precipitation`). An observed change, not a storm total or a snowfall estimate.

## Current, stale and unavailable

Each field of a station's context is one of three states, never a bare number that might be missing:

| `state`       | Has                            | Means                                                                           |
| ------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `current`     | `value`, `freshness`           | Recent enough to show as current.                                               |
| `stale`       | `value`, `freshness`, `detail` | The last value known, older than `freshness.staleAfterMinutes`. Show it as old. |
| `unavailable` | `reason`, `detail`             | No value, and why. `value` is `null`; it is never zero.                         |

Freshness is judged when the response is produced: a cached answer turns `stale` once its age passes the limit. `reason` is a machine-readable code; the ones you will see most:

| `reason`                   | Why there is no value                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `no_data`                  | The station has no readings of that element, or no event is open.                         |
| `insufficient_samples`     | Too few baseline years have a value on this day.                                          |
| `zero_median`              | The median for this day is 0, so a percent of it is undefined.                            |
| `no_climatology`           | No climatology has been built for the sensor.                                             |
| `derived_behind_canonical` | Newer readings arrived after the value was computed; it is withheld until refreshed.      |
| `no_active_version`        | That derivation is not switched on yet.                                                   |
| `unsupported_source`       | The station's data source has not been validated for this calculation; `detail` says why. |

More reasons may be added. Treat one you don't know as unavailable.

## Get a station's current snowpack context

`GET /api/v1/stations/{station}/context` answers "how does today's snow water equivalent compare with history?" in one call. `elements` is always snow water equivalent (SWE, `WTEQ`), snow depth (`SNWD`), precipitation (`PREC`) and air temperature (`TOBS`), in that order; each has its newest reading in `current`, its changes, and, except air temperature, `history`. The example shows snow water equivalent and snow depth; precipitation and air temperature follow in the same shape.

```bash
curl 'https://opensnotel.com/api/v1/stations/312:ID:SNTL/context'
```

```json
{
  "station": "312:ID:SNTL",
  "data": {
    "station": {
      "id": "312:ID:SNTL",
      "name": "Banner Summit",
      "stateCode": "ID",
      "elevationFt": 7040
    },
    "asOf": "2026-03-15T18:00:00.000Z",
    "baseline": { "startWaterYear": 1991, "endWaterYear": 2020 },
    "elements": [
      {
        "elementCode": "WTEQ",
        "current": {
          "state": "current",
          "value": {
            "category": "observed",
            "sensor": {
              "elementCode": "WTEQ",
              "duration": "HOURLY",
              "ordinal": 1,
              "heightDepthIn": null
            },
            "observedAt": "2026-03-15T17:00:00.000Z",
            "localDate": "2026-03-15",
            "value": 12.8,
            "unit": "in",
            "qualityFlag": "V"
          },
          "freshness": {
            "asOf": "2026-03-15T17:00:00.000Z",
            "ageMinutes": 60,
            "staleAfterMinutes": 180
          },
          "reason": null,
          "detail": null
        },
        "change24h": {
          "state": "current",
          "value": {
            "category": "derived",
            "sensor": {
              "elementCode": "WTEQ",
              "duration": "HOURLY",
              "ordinal": 1,
              "heightDepthIn": null
            },
            "windowHours": 24,
            "value": 0.7,
            "unit": "in",
            "quality": "complete",
            "flags": [],
            "start": {
              "observedAt": "2026-03-14T17:00:00.000Z",
              "localDate": "2026-03-14",
              "value": 12.1
            },
            "end": {
              "observedAt": "2026-03-15T17:00:00.000Z",
              "localDate": "2026-03-15",
              "value": 12.8
            },
            "derivation": { "id": "window.wteq_change", "version": 1 }
          },
          "freshness": {
            "asOf": "2026-03-15T17:00:00.000Z",
            "ageMinutes": 60,
            "staleAfterMinutes": 180
          },
          "reason": null,
          "detail": null
        },
        "change72h": {
          "state": "current",
          "value": {
            "category": "derived",
            "sensor": {
              "elementCode": "WTEQ",
              "duration": "HOURLY",
              "ordinal": 1,
              "heightDepthIn": null
            },
            "windowHours": 72,
            "value": 1.4,
            "unit": "in",
            "quality": "partial",
            "flags": ["anchor_within_tolerance"],
            "start": {
              "observedAt": "2026-03-12T18:00:00.000Z",
              "localDate": "2026-03-12",
              "value": 11.4
            },
            "end": {
              "observedAt": "2026-03-15T17:00:00.000Z",
              "localDate": "2026-03-15",
              "value": 12.8
            },
            "derivation": { "id": "window.wteq_change", "version": 1 }
          },
          "freshness": {
            "asOf": "2026-03-15T17:00:00.000Z",
            "ageMinutes": 60,
            "staleAfterMinutes": 180
          },
          "reason": null,
          "detail": null
        },
        "history": {
          "median": {
            "state": "current",
            "value": {
              "category": "derived",
              "localDate": "2026-03-15",
              "value": 10.8,
              "p10": 6.2,
              "p90": 16.4,
              "unit": "in",
              "sampleCount": 30,
              "baseline": { "startWaterYear": 1991, "endWaterYear": 2020 },
              "derivation": {
                "id": "climatology.daily_distribution",
                "version": 1
              }
            },
            "freshness": {
              "asOf": "2026-03-15T08:00:00.000Z",
              "ageMinutes": 600,
              "staleAfterMinutes": 2880
            },
            "reason": null,
            "detail": null
          },
          "percentOfMedian": {
            "state": "current",
            "value": {
              "category": "derived",
              "value": 118.518519,
              "unit": "percent",
              "quality": "complete",
              "flags": [],
              "localDate": "2026-03-15",
              "comparisonCount": 30,
              "of": null,
              "derivation": {
                "id": "climatology.current_relative",
                "version": 1
              }
            },
            "freshness": {
              "asOf": "2026-03-15T08:00:00.000Z",
              "ageMinutes": 600,
              "staleAfterMinutes": 2880
            },
            "reason": null,
            "detail": null
          },
          "percentile": {
            "state": "current",
            "value": {
              "category": "derived",
              "value": 71.666667,
              "unit": "percent",
              "quality": "complete",
              "flags": [],
              "localDate": "2026-03-15",
              "comparisonCount": 30,
              "of": null,
              "derivation": {
                "id": "climatology.current_relative",
                "version": 1
              }
            },
            "freshness": {
              "asOf": "2026-03-15T08:00:00.000Z",
              "ageMinutes": 600,
              "staleAfterMinutes": 2880
            },
            "reason": null,
            "detail": null
          },
          "rank": {
            "state": "current",
            "value": {
              "category": "derived",
              "value": 9,
              "unit": "rank",
              "quality": "complete",
              "flags": [],
              "localDate": "2026-03-15",
              "comparisonCount": 30,
              "of": 31,
              "derivation": {
                "id": "climatology.current_relative",
                "version": 1
              }
            },
            "freshness": {
              "asOf": "2026-03-15T08:00:00.000Z",
              "ageMinutes": 600,
              "staleAfterMinutes": 2880
            },
            "reason": null,
            "detail": null
          }
        }
      },
      {
        "elementCode": "SNWD",
        "current": {
          "state": "stale",
          "value": {
            "category": "observed",
            "sensor": {
              "elementCode": "SNWD",
              "duration": "DAILY",
              "ordinal": 1,
              "heightDepthIn": null
            },
            "observedAt": "2026-03-12T08:00:00.000Z",
            "localDate": "2026-03-12",
            "value": 41,
            "unit": "in",
            "qualityFlag": "V"
          },
          "freshness": {
            "asOf": "2026-03-12T08:00:00.000Z",
            "ageMinutes": 4920,
            "staleAfterMinutes": 2880
          },
          "reason": null,
          "detail": "The newest daily reading is 4920 minutes old."
        },
        "change24h": {
          "state": "unavailable",
          "value": null,
          "freshness": null,
          "reason": "current_missing",
          "detail": "No SNWD reading within the window's end tolerance."
        },
        "change72h": {
          "state": "unavailable",
          "value": null,
          "freshness": null,
          "reason": "current_missing",
          "detail": "No SNWD reading within the window's end tolerance."
        },
        "history": {
          "median": {
            "state": "unavailable",
            "value": null,
            "freshness": null,
            "reason": "insufficient_samples",
            "detail": "Only 6 baseline years have a value on this day."
          },
          "percentOfMedian": {
            "state": "unavailable",
            "value": null,
            "freshness": null,
            "reason": "insufficient_samples",
            "detail": "Only 6 baseline years have a value on this day; a median needs 10."
          },
          "percentile": {
            "state": "unavailable",
            "value": null,
            "freshness": null,
            "reason": "insufficient_samples",
            "detail": "Only 6 comparison years have a value on this day; a percentile or rank needs 10."
          },
          "rank": {
            "state": "unavailable",
            "value": null,
            "freshness": null,
            "reason": "insufficient_samples",
            "detail": "Only 6 comparison years have a value on this day; a percentile or rank needs 10."
          }
        }
      }
    ],
    "events": {
      "active": {
        "state": "current",
        "value": {
          "category": "derived",
          "semantics": "observed_accumulation",
          "sensor": {
            "elementCode": "WTEQ",
            "duration": "DAILY",
            "ordinal": 1,
            "heightDepthIn": null
          },
          "status": "open",
          "active": true,
          "baselineDate": "2026-03-12",
          "startDate": "2026-03-13",
          "endDate": "2026-03-15",
          "durationDays": 3,
          "gainDays": 3,
          "sweGain": {
            "status": "available",
            "value": 1.5,
            "unit": "in",
            "reason": null,
            "detail": null
          },
          "peakDailyGain": {
            "status": "available",
            "value": 0.6,
            "unit": "in",
            "reason": null,
            "detail": null
          },
          "snowDepthChange": {
            "status": "unavailable",
            "value": null,
            "unit": null,
            "reason": "insufficient_coverage",
            "detail": "Snow depth is missing on 2 of the event's days."
          },
          "precipitation": {
            "status": "available",
            "value": 1.6,
            "unit": "in",
            "reason": null,
            "detail": null
          },
          "quality": "complete",
          "flags": [],
          "derivation": { "id": "events.accumulation", "version": 1 }
        },
        "freshness": {
          "asOf": "2026-03-15T00:00:00.000Z",
          "ageMinutes": 1080,
          "staleAfterMinutes": 2880
        },
        "reason": null,
        "detail": null
      },
      "recent": {
        "state": "unavailable",
        "value": null,
        "freshness": null,
        "reason": "no_data",
        "detail": "No closed accumulation event is stored."
      }
    },
    "derivations": [
      {
        "id": "climatology.current_relative",
        "version": 1,
        "configFingerprint": "993acbd7562178d3"
      },
      {
        "id": "events.accumulation",
        "version": 1,
        "configFingerprint": "c55784d666bea18f"
      },
      {
        "id": "window.wteq_change",
        "version": 1,
        "configFingerprint": "82672aae160a5dbe"
      }
    ],
    "mixedVersions": false
  },
  "meta": { "generatedAt": "2026-03-15T18:00:00.000Z" }
}
```

Read it as: 12.8 in of snow water equivalent, up 0.7 in over 24 hours and 1.4 in over 72; 118% of the station's 1991–2020 median for March 15 (10.8 in); the 72nd percentile, ninth highest of 31. Snow depth here is three days old and its history is too thin to compare, so each says so. `mixedVersions` is true only while a rebuild has left two versions of one derivation side by side.

## Plot a water year against the 1991–2020 band

`GET /api/v1/stations/{station}/climatology` returns every day of one water year (October 1 to September 30) of a daily sensor with the station's p10, median and p90 for that day: everything a "this year against normal range" chart needs.

| Parameter   | Values                                     | Default                |
| ----------- | ------------------------------------------ | ---------------------- |
| `element`   | `WTEQ`, `SNWD` or `PREC`                   | `WTEQ`                 |
| `waterYear` | The year the water year ends in, e.g. 2026 | The current water year |
| `previous`  | `true` adds the previous year's values     | `false`                |

```bash
curl 'https://opensnotel.com/api/v1/stations/312:ID:SNTL/climatology?element=WTEQ&waterYear=2026&previous=true'
```

```json
{
  "station": "312:ID:SNTL",
  "data": {
    "station": {
      "id": "312:ID:SNTL",
      "name": "Banner Summit",
      "stateCode": "ID",
      "elevationFt": 7040
    },
    "elementCode": "WTEQ",
    "sensor": {
      "elementCode": "WTEQ",
      "duration": "DAILY",
      "ordinal": 1,
      "heightDepthIn": null
    },
    "unit": "in",
    "unitMismatchDays": 0,
    "waterYear": 2026,
    "start": "2025-10-01",
    "end": "2026-09-30",
    "climatology": {
      "status": "available",
      "reason": null,
      "detail": null,
      "baseline": { "startWaterYear": 1991, "endWaterYear": 2020 },
      "derivation": { "id": "climatology.daily_distribution", "version": 1 }
    },
    "days": [
      {
        "localDate": "2026-02-28",
        "value": 11.2,
        "qualityFlag": "V",
        "band": {
          "status": "available",
          "sampleCount": 30,
          "p10": 5.4,
          "p50": 9.9,
          "p90": 15.1
        }
      },
      {
        "localDate": "2026-03-01",
        "value": null,
        "qualityFlag": null,
        "band": {
          "status": "available",
          "sampleCount": 30,
          "p10": 5.5,
          "p50": 10,
          "p90": 15.2
        }
      },
      {
        "localDate": "2026-03-16",
        "value": null,
        "qualityFlag": null,
        "band": {
          "status": "available",
          "sampleCount": 30,
          "p10": 6.2,
          "p50": 10.9,
          "p90": 16.5
        }
      }
    ],
    "previous": {
      "waterYear": 2025,
      "days": [
        { "localDate": "2025-02-28", "value": 8.9 },
        { "localDate": "2025-03-01", "value": 9 }
      ],
      "unitMismatchDays": 0
    }
  },
  "meta": { "generatedAt": "2026-03-15T18:00:00.000Z" }
}
```

`days` holds all 365 days (366 in a leap water year); three are shown. A day with no reading has `value: null`: March 1 above was missed, and days after today have no value yet. Draw both as gaps, never as zero. A daily value is the reading at the day's local midnight, so in the current water year today's entry carries the sensor's newest hourly reading from today instead, when there is one: that entry alone has `observedAt`, the instant it was read, and it becomes the day's daily value once the day is over. Every value is in `unit`, the unit of the newest reading: a reading the station reported in another unit is left out rather than converted, and `unitMismatchDays` counts those days (in `previous` too), so a nonzero count is worth saying. A history recorded in another unit is not drawn against the season: `climatology.status` is `unavailable` with `unit_mismatch`. `band` is `null` when the station has no climatology; the observed series still comes back, with `climatology.status` `unavailable`. The sensor charted, named in `sensor`, is the station's daily sensor that reported most in that water year, so a replaced sensor gives way to its replacement and their readings are never mixed; `TOBS` has no climatology and is refused with `400`.

## Find the largest 24 h snow water equivalent gains in Idaho

`GET /api/v1/rankings` ranks the stations of a network (SNOTEL, `SNTL`, by default) by one defined measure. There is deliberately no combined "best snow" score.

| `kind`                      | Ranks by                                                                  |
| --------------------------- | ------------------------------------------------------------------------- |
| `wteq_gain_24h`             | Snow water equivalent change over the last 24 hours, from hourly readings |
| `wteq_gain_72h`             | Snow water equivalent change over the last 72 hours                       |
| `snwd_gain_24h`             | Change in snow depth over 24 hours; not snowfall                          |
| `deepest_snowpack`          | The newest daily snow depth (observed)                                    |
| `highest_swe_percentile`    | Today's snow water equivalent percentile against WY1991–2020 for this day |
| `largest_percent_of_median` | Today's snow water equivalent as a percent of its median, only above 100% |
| `strongest_active_event`    | The observed snow water equivalent gain of each open accumulation event   |

| Parameter | Values                                   | Default |
| --------- | ---------------------------------------- | ------- |
| `kind`    | One of the kinds above (required)        |         |
| `state`   | A two-letter state code                  | All     |
| `network` | A network code                           | `SNTL`  |
| `bbox`    | `minLon,minLat,maxLon,maxLat` in degrees | None    |
| `limit`   | 1 to 50                                  | 10      |

```bash
curl 'https://opensnotel.com/api/v1/rankings?kind=wteq_gain_24h&state=ID&limit=2'
```

```json
{
  "data": {
    "kind": "wteq_gain_24h",
    "title": "Largest 24h SWE gain",
    "description": "Snow water equivalent change over the last 24 hours from hourly readings, largest first.",
    "unit": "in",
    "category": "derived",
    "constraints": { "freshnessMinutes": 180, "minQuality": "partial" },
    "scope": { "network": "SNTL", "state": "ID", "bbox": null },
    "stationsConsidered": 82,
    "status": "available",
    "detail": null,
    "entries": [
      {
        "rank": 1,
        "station": {
          "id": "312:ID:SNTL",
          "name": "Banner Summit",
          "stateCode": "ID",
          "elevationFt": 7040
        },
        "value": 0.7,
        "unit": "in",
        "category": "derived",
        "sensor": {
          "elementCode": "WTEQ",
          "duration": "HOURLY",
          "ordinal": 1,
          "heightDepthIn": null
        },
        "freshness": {
          "asOf": "2026-03-15T17:00:00.000Z",
          "ageMinutes": 60,
          "staleAfterMinutes": 180
        },
        "quality": "complete",
        "flags": [],
        "derivation": {
          "id": "window.wteq_change",
          "version": 1,
          "configFingerprint": "82672aae160a5dbe"
        },
        "explanation": "+0.7 in of snow water equivalent over 24 h from hourly readings: 12.1 in on 2026-03-14 to 12.8 in on 2026-03-15."
      },
      {
        "rank": 2,
        "station": {
          "id": "978:ID:SNTL",
          "name": "Mores Creek Summit",
          "stateCode": "ID",
          "elevationFt": 6100
        },
        "value": 0.5,
        "unit": "in",
        "category": "derived",
        "sensor": {
          "elementCode": "WTEQ",
          "duration": "HOURLY",
          "ordinal": 1,
          "heightDepthIn": null
        },
        "freshness": {
          "asOf": "2026-03-15T17:00:00.000Z",
          "ageMinutes": 60,
          "staleAfterMinutes": 180
        },
        "quality": "complete",
        "flags": [],
        "derivation": {
          "id": "window.wteq_change",
          "version": 1,
          "configFingerprint": "82672aae160a5dbe"
        },
        "explanation": "+0.5 in of snow water equivalent over 24 h from hourly readings: 19.5 in on 2026-03-14 to 20 in on 2026-03-15."
      }
    ]
  },
  "meta": { "generatedAt": "2026-03-15T18:00:00.000Z" }
}
```

Only values fresher than `constraints.freshnessMinutes` and of at least `minQuality` rank, so a ranking can hold fewer entries than `limit`, or none; it is never padded with old values. Equal values share a rank. `explanation` says, in words, which readings or dates put the station there. When the derivation a ranking needs is not switched on, `status` is `unavailable`, `detail` says why, and `entries` is empty.

## Caching

The three endpoints are cached for up to five minutes at the CDN (`s-maxage=300`); a past water year's climatology for an hour. Derived values change at most hourly, and freshness is judged on every response.

## Next

- [Provenance](https://opensnotel.com/docs/data/provenance.md): Which values are observed, derived, inferred or forecast, what to credit when you show Snotel data to users, and why a rise in snow depth is not snowfall.
- [Freshness](https://opensnotel.com/docs/data/freshness.md): How recent is this value? Which timestamp is the actual observation time, how often Snotel reads NRCS, when a reading counts as stale, and why a zero can still be fresh.

Canonical page: https://opensnotel.com/docs/api/snowpack
