# Coverage

> How complete and how current each data source is: stations reporting within cadence, when the scheduled reads last delivered, and the known gaps in history with their reason.

`GET /api/v1/coverage` says, for each source Open SNOTEL reads, how many stations it covers, how many reported recently, when its scheduled reads last delivered, and where its history has known holes. The [coverage page](/coverage) shows the same numbers.

```bash
curl 'https://opensnotel.com/api/v1/coverage'
```

```json
{
  "data": {
    "sources": [
      {
        "id": "nrcs.awdb",
        "provider": "nrcs",
        "feed": "awdb",
        "name": "USDA Natural Resources Conservation Service — AWDB REST API",
        "state": "fresh",
        "latestSuccessfulRunAt": "2026-11-14T17:41:12.000Z",
        "feeds": [
          {
            "feed": "observations.hourly",
            "lastSucceededAt": "2026-11-14T17:41:12.000Z",
            "ageMinutes": 19,
            "thresholdMinutes": 180,
            "state": "fresh"
          },
          {
            "feed": "observations.daily",
            "lastSucceededAt": "2026-11-14T08:02:40.000Z",
            "ageMinutes": 597,
            "thresholdMinutes": 2880,
            "state": "fresh"
          }
        ],
        "stations": {
          "basis": "Active SNOTEL stations the NRCS catalog lists with snow water equivalent, snow depth, precipitation or air temperature. …",
          "listed": 4,
          "reporting": 3,
          "share": 0.75,
          "cadence": [
            { "series": "HOURLY", "staleAfterMinutes": 360 },
            { "series": "DAILY", "staleAfterMinutes": 4320 }
          ],
          "measuredAt": "2026-11-14T17:59:30.000Z"
        },
        "gaps": {
          "total": 1,
          "items": [
            {
              "kind": "unread",
              "station": "1305:ID:SNTL",
              "element": null,
              "duration": "DAILY",
              "from": "2001-01-01",
              "to": "2001-12-31",
              "reason": "The source did not answer in time.",
              "reasonCode": "source_timeout"
            }
          ]
        }
      }
    ]
  },
  "meta": { "generatedAt": "2026-11-14T18:00:00.000Z" }
}
```

The example is shortened to one source and a few stations; the NWS section has the same shape.

## Sources

| `id`        | Source                                    | Feeds                                                                          | A station is reporting when                                                                |
| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `nrcs.awdb` | NRCS AWDB, the SNOTEL network             | `observations.hourly`, `observations.daily`                                    | one of its snow, precipitation or temperature sensors has a value newer than its threshold |
| `nws.api`   | National Weather Service, api.weather.gov | `weather.forecast`, `weather.observations`, `weather.alerts`, `weather.points` | the forecast for its NWS grid cell was fetched within three hours                          |

More sources are added as Open SNOTEL reads them; treat an unknown `id` as one more section.

## Freshness

Each feed is judged when the response is sent, by the rules Open SNOTEL's own staleness alert uses, so this endpoint and the alert never disagree:

| `state`    | Means                                                                     |
| ---------- | ------------------------------------------------------------------------- |
| `fresh`    | A run delivered within `thresholdMinutes`.                                |
| `stale`    | A run delivered once, but not within the threshold.                       |
| `never`    | No run of the feed has delivered yet.                                     |
| `inactive` | The feed isn't expected to deliver yet. It doesn't make the source stale. |

A run "delivers" when it finishes with everything or most of it stored. A source's `state` is its least current expected feed, and `latestSuccessfulRunAt` is the newest delivery of any of its feeds.

A feed being fresh says Open SNOTEL is reading the source on schedule. Whether each station has new data is `stations`: a station can go quiet (a failed sensor, a telemetry outage) while the feed keeps running. Station counts are taken at `measuredAt`, at most a minute or so before the response. See [Freshness](https://opensnotel.com/docs/data/freshness.md) for the thresholds.

## Known gaps

`gaps.items` lists up to 50 known gaps, by station; `gaps.total` counts them all.

| `kind`           | Means                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `source_missing` | The source can't serve this element for the station from `from` on. Nothing is filled in.              |
| `unread`         | A range of history Open SNOTEL tried to read and couldn't, and hasn't read since. `reasonCode` is why. |
| `not_covered`    | The source has nothing for this station at all, such as a station outside NWS's forecast grids.        |

`reason` explains a gap in words; it is `null` when the reason isn't known. `reasonCode` is an open string: new codes may appear. A gap Open SNOTEL reads again later disappears from the list.

The response is cached for up to a minute.

## Next

- [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.
- [Errors](https://opensnotel.com/docs/api/errors.md): Handle API errors: the one error shape every endpoint returns, each code with its HTTP status, and what to do about it.

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