1. Home
  2. API documentation
  3. API endpoint examples

Back to API endpoint examples

  • API endpoint examples
  • Who we are

Time series data queries

The time series path

As described in the section, How the data are structured, time series data may be referenced by their hierarchical position in the data archive:

Further, each individual time series has a unique identification code number: its time series ID (ts_id). In order to facilitate retrieving commonly associated groups of time series, e.g. An Example, pre-configured groups are identified by a time series group ID.

Construct a time series path

As described, a ts_path query argument, constructed from site_no, station_no, parameter_no, and ts_shortname - or simply returned by a ts_path return field - can be used to identify time series to be returned in getTimeseriesValues queries.

All stations in SEPA's duplicate data archive accessed via the API are grouped under site '1'. The station is identified by its number (sta_no_s), e.g. 9683. The parameter is identified by its short name, e.g. SG. The time series is identified by its short name, e.g. 15m.Cmd. The path components are separated by forward-slashes, to produce, e.g. 1/9683/SG/15m.Cmd

Retrieve a time series ID

The time series ID, ts_id, is the default identifier retrieved by getTimeseriesList queries.

These use cases relate to time series values

Table of contents
Select a section to jump to:

Retrieve the last value for a given time series

Retrieve the last year's worth of values for a given time series

access to the same data using the path (1/9683/SG/15m.Cmd)

All river levels for the last week

Data for multiple time series can be retrieved either using a comma separated list of time series IDs, using the time series path with wildcards (*) or using a time series group ID.

Timeseries IDs can be retrieved with getTimeseriesList to create a comma separated list.

All level (SG) high resolution time series are in the path 1/*/SG/15m.Cmd

The time period can be requested specifically with &from=YYYY-mm-DD&to=YYYY-mm-DDTHH:MM:ss or by requesting a period with &period=PnD, where n is the number of days.

Last value for all river levels as a map layer

retrieving the last value for a time series group

Group IDs can be found using getGroupList. This group includes time series from river and tidal level stations.

As above but with selected metadata

Daily Mean Flow data for a station

Annual Maximum data for a station

Peaks-over-Threshold data for a station

Peak-over-threshold data are held in a time series with short name POT

Long-term maximum, minimum, and mean data for all river level stations

Example The number of time series exceeds the API limit of 1000, so this must be issued as 3 requests

Maximum:

Minimum:

Mean:

Gaugings

Flow gaugings are accessed via timeseries with a short name Cmd.Gaugings.  For gaugings it is normal to be interested in the gauged flow and the level.  To access the level for the gauging an additional return field, Stagesource Value, must be specified as below.

Rainfall Queries

Note a list of stations where rainfall is measured is available with the request

Fifteen Minute Rainfall

15 minute totals are the highest resolution available via the API and is stored in a time series with short name 15m.Total so the path of the data is 1/StationNo/RE/15m.Total. 

Example: for station number 15201 (Edinburgh Royal Botanic Gardens), for 3 months of data (period=P3M), the request is as below.  For other stations simply replace the station number with the number of the station you are interested in.

Hourly Rainfall

Hourly totals are stored in a time series with short name Hour.Total so the path of the data is 1/StationNo/RE/Hour.Total.  A period of 7 days of data can be accessed with the period=P7D for example.  For station number 344764 (Prestwick) the request is as below.  For other stations simply replace the station number with the number of the station you are interested in.

Daily Rainfall data

Daily rainfall is is time series with short name HDay.Total so the path of the data is 1/StationNo/RE/HDay.Total.  A period of 1 year can be accessed with the period=P1Y.  For station number 14897 (Bannockburn) the request is as below.  For other stations simply replace the station number with the number of the station you are interested in.

Monthly Rainfall

Example request: monthly rainfall totals are in time series with short name HMonth.Total so the path of the data is 1/StationNo/RE/HMonth.Total.  A period of 10 years can be accessed with the period=P10Y.  For station number 115343 (Glen Nevis) the request is as below.  For other stations simply replace the station number with the number of the station you are interested in.

Annual rainfall totals for the calendar year are in time series with short name CYear.Total. Data for the hydrological year are also available in HYear.Total.  The path of the calendar year total data is 1/StationNo/RE/CYear.Total.  The complete record of data is available using period=complete.  For station number 116042 (Castle Kennedy) the request is as below.  For other stations simply replace the station number with the number of the station you are interested in.