This is a BETA service - your feedback will help us improve the service.

Time series data queries

return the time series data values

N.B. It is useful to review the discussion of the pros and cons of ts_id and ts_path prior to preceding with this section.

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:

Site : Station : Parameter : Time series

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

N.B. Additional metadata can be returned from getTimeseriesValues queries by adding &metadata=true at the end of the request, and then specifying the required fields.

These use cases relate to time series values

Retrieve the last value for a given time series

Example : access time series data for ts_id=61573010 (15-minute Level at Galashiels)
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=61573010&returnfields=Timestamp,Value,Quality Code
N.B. only the last value is returned because time range and period are unspecified.

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)

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/9683/SG/15m.Cmd&period=P1Y&returnfields=Timestamp,Value,Quality Code
N.B. &period=P1Y returns a year of data; if no &from or &to dates are specified, it defaults to a year ending at the last timestamp of the requested time series.

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/*/SG/15m.Cmd&period=P7D&returnfields=Timestamp,Value,Quality Code

Last value for all river levels as a map layer

As above but using getTimeseriesValueLayer, which is a more efficient call for retrieving single data values for multiple stations. However, it only offers limited return data formats.

retrieving the last value for a time series group

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&timeseriesgroup_id=41804&format=geojson&returnfields=Timestamp,Value,Quality Code
Example : return data as value layer, requesting geojson format
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValueLayer&timeseriesgroup_id=41804&format=geojson&returnfields=timestamp,ts_value,q_code
N.B. the return fields are named differently with getTimeseriesValueLayer

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

Daily Mean Flow data for a station

Daily Mean Flow data is stored in a time series with the short name HDay.Mean.

Example : A request for daily mean flow from Ballathie (Station number 14937) for the period 01/01/2000 to 01/01/2010
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/14937/Q/HDay.Mean&from=2000-01-01&to=2010-01-01&metadata=true&returnfields=Timestamp,Value,Quality Code

Annual Maximum data for a station

Example : both Flow (Q) and Level (SG) Annual Maximum data for the Tweed, at Norham
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/9514/Q/HYear.Max,1/9514/SG/HYear.Max&period=complete&metadata=true&returnfields=Timestamp,Value,Occurrance Timestamp,Quality Code&dateformat=yyyy-MM-dd HH:mm:ss
N.B. both Timestamp and Occurrance Timestamp (sic) are specified as return fields - Minimum and maximum values have a timestamp for the aggregation period - in this case a year - which is typically the start of the day, month, or year, and a timestamp identifying when  the event (minimum or maximum) occurred.

Peaks-over-Threshold data for a station

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

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/9514/*/POT&period=complete&metadata=true&returnfields=Timestamp,Value,Quality Code

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

N.B. only one year of data is required for long-term values as the values repeat each year, hence the query argument &period=P1Y

Maximum:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/*/SG/LTV.HMonth.Max&period=P1Y&metadata=true&returnfields=Timestamp,Value,Quality Code

Minimum:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/*/SG/LTV.HMonth.Min&period=P1Y&metadata=true&returnfields=Timestamp,Value,Quality Code

Mean:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/*/SG/LTV.HMonth.Mean&period=P1Y&metadata=true&returnfields=Timestamp,Value,Quality Code
Example : A registered user with an access key is not constrained by the 1000 time series limit and could issue a single request to retrieve maximum, mean, and minimum simultaneously:
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/*/SG/LTV.HMonth.M*&period=P1Y&metadata=true&returnfields=Timestamp,Value,Quality Code
Example : Minimum and mean can be retrieved simultaneously:
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=gettimeseriesvalues&ts_path=1/*/SG/LTV.HMonth.M*n&period=P1Y&metadata=true&returnfields=Timestamp,Value,Quality Code
Example : as an alternative, return a list of all the time series IDs for the minimum, mean, and maximum long-term values, and then build these into a very long list of values to specify the ts_id query arguments. This approach is best used programmatically, rather than constructing the query manually.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&stationparameter_no=SG&ts_name=LongTermValue.Month.*&returnfields=station_name,ts_id, ts_name
N.B. neither csv or xlsx formats are true tabular formats - metadata is obscured in header rows rather than being column headers for the data

 

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/*/Q/Cmd.Gaugings&period=P1Y&returnfields=Timestamp,Value,Quality Code,Stagesource Value&metadata=true

Rainfall Queries

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

timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getstationlist&stationparameter_name=Rain&flatten=true&returnfields=station_name,station_no,station_latitude,station_longitude
The format of the returned data can be changed by adding different format switches to the end of the request, for example format=json or format=csv&csvdiv=,
For information about the time period of returned data please see here.

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/15201/RE/H15m.Total&period=P3M&returnfields=Timestamp,Value,Quality Code,Stagesource Value&metadata=true

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/344764/RE/Hour.Total&&from=2023-01-01&to=2023-01-29&returnfields=Timestamp,Value,Quality Code&metadata=true

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/14897/RE/HDay.Total&period=P1Y&returnfields=Timestamp,Value,Quality Code,Stagesource Value&metadata=true

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/115343/RE/HMonth.Total&period=P10Y&returnfields=Timestamp,Value,Quality Code&metadata=true

Complete Record of Yearly Totals

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.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/116042/RE/CYear.Total&period=complete&returnfields=Timestamp,Value,Quality Code&metadata=true

for annual totals from all stations use 

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/*/RE/CYear.Total&period=complete&returnfields=Timestamp,Value,Quality Code&metadata=true