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

Principal query functions

Detailed information on the principal API functions

These functions satisfy the majority of common use cases

Examples of some miscellaneous queries may be found in Other endpoints

getGroupList

Groups provide a convenient means of retrieving data from a pre-configured set of stations, parameters, or time series via a single identifier, stationgroup_id, parametergroup_id, or timeseriesgroup_id, respectively. The getGroupList query function retrieves a list of configured groups. 

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGroupList
N.B. the group identifiers are returned as group_id but specified in getStationList, getTimeseriesList, getTimeseriesValues, and getTimeseriesValueLayer as stationgroup_id, parametergroup_id or timeseriesgroup_id

Applicable return formats:

  • ascii
  • csv
  • html
  • json
  • tabjson
  • objson
  • xlsx

getStationList

The getStationList query function retrieves a list of stations, optionally with metadata.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getStationList

Metadata associated with stations include the number, name, catchment identifiers and positional information. Retrieve all standard station metadata fields using returnfields=all 

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getStationList&station_no=15018&returnfields=all
N.B. by default returnfields=all forces flatten=true and cannot be overridden, other than by specifying all return fields explicitly

Careful selection of the available return fields produces a targeted request.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getStationList&returnfields=station_no, station_name,catchment_name,station_latitude,station_longitude,stationparameter_name, stationparameter_no&object_type=General
N.B. getStationList will return multiple entries where there are separate object_type values even when this field is not specifically requested.  This results in apparent duplicate return lines per station. The duplicate lines can be removed by specifying object_type=General

The returned data may be further compressed to a single entry per station by concatenating multiple parameter entries (stationparameter_name and stationparameter_no) into single semicolon-separated fields. Use flatten=true. In this case object_type=General may be omitted.

Example : concatenate multiple parameter field entries into single entries per station
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getStationList&returnfields=station_no, station_name,catchment_name,station_latitude,station_longitude,stationparameter_name, stationparameter_no&flatten=true

In addition to the standard fields, SEPA has configured custom attribute data to store other network information and to deliver particular management tools. These data are requested by specifying ca_sta as a return field and then specifying the fields of interest using ca_returnfields.  If ca_returnfields is unspecified, ca_sta will return all custom attribute fields, i.e. there is no need to specify ca_returnfields=all.

The getStationList function can be filtered using query fields  that broadly correspond to the return fields - the definitive list of query fields is available in the Kisters documentation

Example : retrieve metadata for stations filtered by stationparameter_no and catchment_name
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getStationList&stationparameter_no=SG&catchment_name=Tweed&returnfields=station_no, station_name,catchment_name,station_latitude,station_longitude,stationparameter_name, stationparameter_no&object_type=General

Applicable formats:

  • ascii,
  • csv,
  • html,
  • json,
  • tabjson,
  • objson,
  • geojson,
  • kml,
  • lpk,
  • xlsx

getParameterList

Retrieves a list of parameters available at sites and/or stations. Very similar functionality to getStationList, but with the focus on parameters. This may be useful to find out which stations record which parameters, for example Rainfall or Level, and details about the parameter measurements, for example measurement units. Using getStationlist or getTimeseriesList often proves more useful.

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getParameterList

Applicable formats:

  • ascii,
  • csv,
  • html,
  • json,
  • tabjson,
  • objson,
  • xlsx

getTimeseriesList

Retrieves a list of time series with metadata. Returned metadata can include information about the time series, parameter, and station. The return field coverage provides the temporal extent of the time series.

Example : retrieve details of a particular type of time series by specifying ts_name, at all stations where that time series exists
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&ts_name=PeaksOverThreshold&stationparameter_name=Flow&returnfields=station_no,station_name,catchment_name,station_latitude,station_longitude,stationparameter_name,ts_name,ts_id,ts_path,coverage
N.B. the ts_id and ts_path fields are the principal identifiers required to subsequently retrieve time series data values using the getTimeseriesValues query

The time series data identifiers - ts_id and ts_path - deserve a little more attention: both can be returned from the getTimeseriesList request and either can be used to configure subsequent getTimeseriesValues or getGraph reqests, but which should be used when, and are they interchangeable?The key is:

  • if you've determined a collection of time series (potentially using a one or more filters, possibly on metadata fields) with getTimeseriesList and have a programmatic means to extract the ts_id values and turn them into a list of comma-separated arguments to &ts_id= then choose this approach, or
  • if you want to return a collection of time series that may be filtered on the basis of their structural identifiers - station_no, stationparameter_no, and ts_name - as used to build the ts_path , using wildcards (*) on their text values and have the option of doing this as part of the getTimeseriesValues or getGraph requests, then this is the guy for you.

In essence, if your group of time series is defined by either of the parameter of the time series type, you can skip the getTimeseriesList step and perform the filter in the getTimeseriesValues/getGraph step; otherwise, you'll need to perform the (more complex) filter via the getTimeseriesList request, and build the resulting list of ts_id values into the getTimeseriesValues/getGraph requests - easy for a few, manually, less so for many!

Example : retrieve details of all time series available at one station for a particular parameter filter by station_name and stationparameter_name. Omit the stationparameter_name filter to retrieve all time series at a station.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Friars*&stationparameter_name=Level&returnfields=station_no,station_name,stationparameter_name,ts_name,ts_id,ts_path,coverage

Applicable formats:

  • ascii
  • csv
  • html
  • json
  • objson
  • geojson
  • kml
  • lpk
  • xlsx

getTimeseriesValues

Retrieves time series data values. These are the results of environmental measurements, the main focus of the API. The time series to return are specified by either their ts_id, which may be a comma-separated list of values, by their ts_path, which may include wildcards, or by a timeseriesgroup_id. Time series values are often retrieved for a period of time, e.g. a week, a year, or a few days. Specify the required period of data by referring to Specifying date and time. If no time period is specified then the last value for the time series is returned.

Examples : the same request, specified by ts_path and by ts_id using values returned from the second getTimeseriesList example above
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/133156/SG/HDay.Mean&period=P2W&to=2021-01-17
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=53912010&period=P2W&to=2021-01-17

It is important to return the quality codes with time series data as these indicate if the data is of good quality.

Example : retrieve station metadata with time series values by including metadata=true. Additional fields are added by using md_returnfields and still more by adding custom attribute fields with ca_sta with ca_sta_returnfields.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/*/SG/HMonth.Max&period=P1Y&returnfields=Timestamp,Value,Quality Code,Occurrance Timestamp&metadata=true&md_returnfields=station_no,station_name,station_latitude,station_longitude,stationparameter_name,river_name,ca_sta&ca_sta_returnfields=CATCHMENT_SIZE,GAUGE_DATUM

Optional fields that modify the returned data are;

  • gapdetaction (gapdetection=fillgaps) fills gaps in equidistant time series returning a time stamp for each interval of the time series even if there is no values in the period
  • valueasstring - only with json format, fills nulls with 'null' rather than leaving a true null 
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/133123/Q/HDay.Mean&from=2021-12-01&to=2022-02-01&metadata=true&gapdetection=fillgaps&returnfields=Timestamp, Value, Quality Code&valueasstring&format=json

Gaugings

Flow gaugings are accessed via the getTimeseriesValues request, using either the ts_id retrieved from a time series list, or with the path and time series 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

Applicable formats:

  • ascii
  • csv
  • html
  • json
  • dajson
  • wml2
  • zrxp
  • xlsx

getTimeseriesValueLayer

Retrieves timeseries data as layer. Similar to getTimeseriesValues, but much more efficient for getting single or last values for geographical representation.

N.B. getTimeseriesValueLayer and getTimeseriesValues use metadata=true&md_returnfields and returnfields arguments, respectively
Example : retrieve the last value of Daily Maximum Level for all stations specifying ts_path with wildcard
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValueLayer&ts_path=1/*/SG/HDay.Max&returnfields=timestamp,ts_value,q_code,occ_timestamp,sta_location&metadata=true&ca_sta_returnfields=CATCHMENT_SIZE,GAUGE_DATUM&md_returnfields=stationparameter_name,ts_unitname,ts_unitsymbol,station_no,station_name,ca_sta,catchment_name
N.B. data for the whole 'layer' can be retrieved for a specific timestamp by specifying the date query argument. The data are those most recent to the specified date.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValueLayer&ts_path=1/*/SG/HDay.Max&returnfields=timestamp,ts_value,q_code,occ_timestamp,sta_location&date=2020-05-13&dateformat=yyyy-MM-dd HH:mm:ss

Applicable formats:

  • ascii
  • csv
  • html
  • json
  • objson
  • geojson
  • xlsx

getGraph

Whilst the preceding requests have focused on working towards retrieving numerical data and metadata, sometimes it's useful to get a quick visualisation of the returned data (or a subset) in order, for example, to confirm or identify a particular period of interest, or to add context with long-term statistics - in this instance the getGraph query is your friend. Similar to getTimeseriesValues, the specific time series are specified using ts_path, ts_id, or timeseriesgroup_id, and may include wildcards and comma-separated values, respectively. The default return format is PNG.

Example : the data (HDay.Max) returned in the getTimeseriesValues example above, with the addition of HDay.Min, HDay.Mean,15m.Cmd, HMonth.Max, and HMonth.Min

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&ts_id=53912010,53911010,53913010,53907010,53917010,53919010&period=P2W&to=2021-01-17

Applicable formats:

  • jpg
  • png