# API overview

> Use the REST API at /api/v1: every endpoint, the conventions all responses follow (UTC times, null for missing, the source's units and flags), request bounds and caching.

The REST API is public, read-only and needs no key. It lives under `/api/v1` on this site; there is no separate API host. Every value in it keeps the source's unit and flags, and a missing reading is `null`, never zero.

## Make a request

```bash
curl 'https://opensnotel.com/api/v1/stations/312:ID:SNTL/latest?elements=SNWD&duration=HOURLY'
```

```json
{
  "station": "312:ID:SNTL",
  "data": [
    {
      "elementCode": "SNWD",
      "duration": "HOURLY",
      "ordinal": 1,
      "heightDepthIn": null,
      "unit": "in",
      "observedAt": "2026-10-23T19:00:00.000Z",
      "localDate": "2026-10-23",
      "value": 1,
      "flag": "R",
      "qualityFlag": "V",
      "isProvisional": null,
      "sourceUpdatedAt": "2026-10-23T20:05:00.000Z",
      "newestObservedAt": "2026-10-23T19:00:00.000Z",
      "freshness": { "state": "fresh", "staleAfterMinutes": 360 }
    }
  ],
  "meta": { "generatedAt": "2026-10-23T21:20:00.000Z" }
}
```

## Endpoints

| Method and path                               | Returns                                                               | Page                                   |
| --------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------- |
| `GET /api/v1/stations`                        | A page of stations                                                    | [Stations](https://opensnotel.com/docs/api/stations.md)         |
| `GET /api/v1/stations/{station}`              | One station and what it reports                                       | [Stations](https://opensnotel.com/docs/api/stations.md)         |
| `GET /api/v1/stations/{station}/latest`       | The newest reading of each sensor, with freshness                     | [Observations](https://opensnotel.com/docs/api/observations.md) |
| `GET /api/v1/stations/{station}/observations` | Readings over a date range                                            | [Observations](https://opensnotel.com/docs/api/observations.md) |
| `GET /api/v1/stations/{station}/context`      | Snowpack Context: recent change and comparison with history           | [Snowpack Context](https://opensnotel.com/docs/api/snowpack.md) |
| `GET /api/v1/stations/{station}/climatology`  | A water year against the station's WY1991–2020 band                   | [Snowpack Context](https://opensnotel.com/docs/api/snowpack.md) |
| `GET /api/v1/rankings`                        | Stations ranked by recent gain, depth or anomaly                      | [Snowpack Context](https://opensnotel.com/docs/api/snowpack.md) |
| `GET /api/v1/stations/{station}/weather`      | NWS weather around the station: nearby observations, forecast, alerts | [Weather](https://opensnotel.com/docs/api/weather.md)           |
| `GET /api/v1/stations/nearest`                | The stations nearest a point                                          | [Nearest stations](https://opensnotel.com/docs/api/nearest.md)  |
| `GET /api/v1/resorts`                         | A page of North American ski resorts                                  | [Resorts](https://opensnotel.com/docs/api/resorts.md)           |
| `GET /api/v1/resorts/{resort}`                | One resort with its operating area and provenance                     | [Resorts](https://opensnotel.com/docs/api/resorts.md)           |
| `GET /api/v1/coverage`                        | How complete and current each data source is, with known gaps         | [Coverage](https://opensnotel.com/docs/api/coverage.md)         |
| `GET /api/v1/openapi.json`                    | The OpenAPI document                                                  | [OpenAPI](https://opensnotel.com/docs/reference/openapi.md)     |

`{station}` is always the [station triplet](https://opensnotel.com/docs/reference/station-ids.md), such as `312:ID:SNTL`. Percent-encoded colons work too. `{resort}` is a resort's slug, such as `bogus-basin-mountain-recreation-area`.

## Conventions

- **Times.** Instants such as `observedAt` are ISO 8601 in UTC. `localDate` is the station's calendar day, from the fixed offset in `utcOffsetMinutes`; see [time and dates](https://opensnotel.com/docs/reference/time.md).
- **Missing values.** `value` is `null` when the source reported none. It is never zero, and the row is still returned so a gap can be told from a quiet sensor.
- **Flags and units.** `flag`, `qualityFlag` and `unit` are the source's, unchanged; [quality](https://opensnotel.com/docs/data/quality.md) explains them. `originalValue` keeps the reading as first received when the source later edited or blanked it.
- **Observed unless labeled.** The station, latest and observations endpoints return observed values only, and no snowfall is computed from depth. The [Snowpack Context](https://opensnotel.com/docs/api/snowpack.md) endpoints add derived values (changes, comparisons with history, accumulation events), each labeled `derived` with the derivation version that produced it. The [weather](https://opensnotel.com/docs/api/weather.md) endpoint also returns NWS forecasts and observations from nearby NWS stations, and labels every value with its `kind`. See [provenance](https://opensnotel.com/docs/data/provenance.md).
- **`meta.generatedAt`.** When the answer was computed. Answers are cached, so it can be a little earlier than the response.

## Bounds

Requests are bounded so no call can ask for the whole dataset.

| Limit                           | Value                 |
| ------------------------------- | --------------------- |
| Stations per page               | 1 to 500, default 100 |
| Resorts per page                | 1 to 500, default 100 |
| Elements per request            | 10                    |
| Daily observations per request  | 366 days              |
| Hourly observations per request | 31 days               |
| Readings per response           | 20,000                |
| Nearest stations                | 25, within 500 km     |
| Ranking entries                 | 1 to 50, default 10   |

A request over a limit answers `422` with `range_too_large` and the limit; see [errors](https://opensnotel.com/docs/api/errors.md).

## Caching

Reads are cached and served with public `Cache-Control` headers. Latest conditions are shared for about a minute, and a new reading invalidates them as soon as it is stored. Station metadata, the resort registry and settled history are cached for an hour. A range that reaches into the last three days, which can still be revised, is cached for five minutes. Freshness is judged when the response is sent, not when the data was cached.

## Usage & pricing

The API is free, without a key, for personal, non-commercial, educational, research, journalistic and nonprofit use, and for evaluating or prototyping a commercial product, within the rate limits ([Terms, section 3](/terms#3)).

Commercial use needs a commercial plan or a written agreement ([section 4](/terms#4)). That covers a paid, subscription or ad-supported product, internal use by a for-profit business, AI or agent products that call the API for their users, reselling, redistributing, bulk downloading, caching or mirroring responses as a dataset or service, and any use above the free rate limits. Until self-serve plans are available, [Pricing](/pricing) has the contact.

Clients also agree to the [API and MCP rules](/terms#5), such as respecting `429` responses and `Retry-After` (see [rate limits](https://opensnotel.com/docs/api/errors.md#rate-limits)). The [Terms of Use](/terms) and [Privacy Policy](/privacy) cover the rest.

## The machine-readable reference

`GET /api/v1/openapi.json` is the OpenAPI 3.1 description of every operation above, built from the same schemas the API serves with. See [OpenAPI](https://opensnotel.com/docs/reference/openapi.md).

## Next

- [Stations](https://opensnotel.com/docs/api/stations.md): List or search stations by name, state or network, and get one station by its triplet: location, elevation, UTC offset, period of record and the measurements it reports.
- [OpenAPI](https://opensnotel.com/docs/reference/openapi.md): Where the machine-readable OpenAPI 3.1 document for /api/v1 lives, what it covers, and how to generate a typed client from it.

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