# Stations

> 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.

The stations endpoints list stations and return one by its triplet. A station is identified by its [station triplet](https://opensnotel.com/docs/reference/station-ids.md) and nothing else.

## List stations

`GET /api/v1/stations` returns a page of stations ordered stably, so paging never repeats or skips one.

| Parameter  | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| `q`        | Part of the station name, case-insensitive, 2 to 100 characters. |
| `state`    | Two-letter state code, such as `ID`.                             |
| `network`  | Network code, such as `SNTL`.                                    |
| `active`   | `true` for active stations only, `false` for inactive only.      |
| `provider` | Which provider's stations to list, by code. Default `nrcs`.      |
| `limit`    | Stations per page, 1 to 500. Default 100.                        |
| `cursor`   | The `page.nextCursor` of the previous page.                      |

```bash
curl 'https://opensnotel.com/api/v1/stations?state=ID&q=banner&limit=1'
```

```json
{
  "data": [
    {
      "id": "312:ID:SNTL",
      "name": "Banner Summit",
      "stateCode": "ID",
      "networkCode": "SNTL",
      "latitude": 44.30342,
      "longitude": -115.23447,
      "elevationFt": 7040,
      "utcOffsetMinutes": -480,
      "isActive": true,
      "periodOfRecord": { "start": "1979-10-01", "end": null }
    }
  ],
  "page": { "limit": 1, "nextCursor": null },
  "meta": { "generatedAt": "2026-10-23T21:20:00.000Z" }
}
```

`page.nextCursor` is `null` on the last page. A cursor is opaque: hand it back as `cursor` and do not parse it. A cursor the API did not issue is an `invalid_parameter` error.

## Get one station

`GET /api/v1/stations/{station}` returns the station and the measurements it reports, so you can see which elements to ask for before asking.

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

```json
{
  "data": {
    "id": "312:ID:SNTL",
    "name": "Banner Summit",
    "stateCode": "ID",
    "networkCode": "SNTL",
    "latitude": 44.30342,
    "longitude": -115.23447,
    "elevationFt": 7040,
    "utcOffsetMinutes": -480,
    "isActive": true,
    "periodOfRecord": { "start": "1979-10-01", "end": null },
    "elements": [
      {
        "elementCode": "SNWD",
        "duration": "DAILY",
        "ordinal": 1,
        "heightDepthIn": null,
        "unit": "in",
        "isDerived": false,
        "isAvailable": true,
        "periodOfRecord": { "start": "2000-08-23", "end": null }
      }
    ],
    "missingData": []
  },
  "meta": { "generatedAt": "2026-10-23T21:20:00.000Z" }
}
```

## Fields

- `id` is the station triplet. `stateCode` and `networkCode` are its parts.
- `publicId` is the station's id across providers. For an NRCS station it is the triplet, the same as `id`; another provider's station is `<provider>:<provider station id>`. See [station IDs](https://opensnotel.com/docs/reference/station-ids.md#public-ids).
- `source` says who publishes the station's data and how to credit it; see [source](#source) below.
- `latitude`, `longitude` and `elevationFt` are `null` when the source's value is missing or out of range.
- `utcOffsetMinutes` is the fixed offset of the station's local standard time; there is no daylight saving. See [time and dates](https://opensnotel.com/docs/reference/time.md).
- `isActive` is `null` when the source does not say. A station that stopped reporting is still listed, with the end of its `periodOfRecord`.
- Each element is one sensor: `ordinal` tells several sensors of one element apart, and `heightDepthIn` is a sensor's height (positive) or depth (negative) in inches. `isAvailable` is `false` once the source stopped listing it; its history remains. `periodOfRecord` is the span with data, so a sensor can have fewer readings than days in it. [Measurements](https://opensnotel.com/docs/data/measurements.md) defines the element codes.
- `missingData` lists elements the source can't serve for this station, with the first missing local date (`from`) and the `reason`, oldest first. Those readings are absent from observations, never filled in. It is `[]` for nearly every station. The service always sends it, but it was added after v1, so treat an absent list as empty. Each entry's `source` says where it came from:
  - `curated`: listed by hand. It is open-ended (no `to`) and covers every duration; Open SNOTEL doesn't read the element from `from` on.
  - `automatic`: ingest found the source answering an error (HTTP 500) for the element even when asked for it alone. It is bounded by `to`, the last missing local date, and names the one `duration` (`DAILY` or `HOURLY`) it covers. Open SNOTEL keeps asking for the element: recent dates are asked for again on the next scheduled read, and the entry shrinks or goes once the source serves them. Older dates, recorded by a backfill, stay listed until a backfill reads them again.

  `to`, `duration` and `source` were added later and are optional: an entry without `source` is `curated`.

## Source

Every station carries where its data comes from, taken from the [data sources](https://opensnotel.com/docs/data/sources.md) registry:

```json
{
  "publicId": "312:ID:SNTL",
  "source": {
    "provider": "nrcs",
    "feed": "awdb",
    "name": "USDA Natural Resources Conservation Service — AWDB REST API",
    "network": "SNTL",
    "countryCode": "US",
    "region": "ID",
    "attribution": "USDA Natural Resources Conservation Service, National Water and Climate Center",
    "licenseStatus": "pending",
    "license": null,
    "licenseUrl": null
  }
}
```

- `provider` and `feed` are the registry's codes; `name` spells them out.
- `network` is the provider's own network for the station, and `region` its own region code: a US state for NRCS, not necessarily a state elsewhere. `countryCode` is ISO 3166-1 alpha-2, or `null` when a provider spans countries and does not say.
- `attribution` is the credit line to show wherever the station's data is shown.
- `licenseStatus` is `verified` once a person has checked the provider's terms and `pending` until then; `license` and `licenseUrl` name the licence when one is recorded.

`publicId` and `source` were added after v1. The service always sends them, but treat them as optional.

Lists and searches cover one provider at a time. Without `provider` that is `nrcs`, so another provider's stations never appear in a default list; ask for them by code.

An unknown station answers `404` with `station_not_found`; an id that is not a triplet answers `400`. See [errors](https://opensnotel.com/docs/api/errors.md).

## Next

- [Nearest stations](https://opensnotel.com/docs/api/nearest.md): Find the SNOTEL stations nearest a latitude and longitude, or nearest another station, ranked by great-circle distance, with limit and radius filters.
- [Station IDs](https://opensnotel.com/docs/reference/station-ids.md): The identifier to store for a station: the NRCS triplet such as 312:ID:SNTL, its format, why the station number alone isn't unique, and a parser.

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