API function reference

This page describes how queries supported by the API are structured, and provides a walk-through of the process of exploring and returning specific time series data. The full list of available functions are also summarised in the built-in documentation.

• The central concept
• The anatomy of a query
• Building a specific query function
• Metadata
• A walk-through of a time series data request

N.B. All of the example HTTP requests should work!
Either copy the text and paste it into a browser address bar,
or select and right-click to access 'Open Link in New Tab'.
You can then experiment with tweaking the arguments to return different data.

The central concept

In the background, all of the time series data are stored in a single database table and each data value is uniquely referenced by its timestamp and time series ID, ts_id. In order to navigate to specific records using a nomenclature that describes the data's physical provenance (where, what, and how often), they are located within a hierarchical structure and attributed a range of identifiers and metadata, as described in the data structure section. Each level of this hierarchy can be interrogated via the API to return lists of the subordinate data and, most importantly, their referencing identifiers.

The API query functions include filtering capabilities on both identifiers and metadata, and these can be used to home in on specific subsets of the total data collection. The resulting lists of identifiers can then be used to generate targeted simultaneous requests for both time series data and associated metadata.

The quick start walk-through below should lead you through the process of interrogating and filtering each level of the hierarchy to arrive at targeted data requests, and provide a model for your own exploration of the available data.

The anatomy of a query

There are up to six components of a query to the API:

• API root URL - this is the primary connection to the API
• back-end configuration - fixed for this service
• query function - this determines what type of request is made
• query arguments - these filter the request to reduce the number of returned entries; some (text fields) may be used to form 'fuzzy' filtering by using the asterisk wildcard.
• return fields - these determine which elements of an entry to return
• return format - this specifies the presentation of the returned data

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&datasource=0&type=queryServices&request=getStationList&station_name=Auch*&returnfields=station_name, station_no, station_latitude, station_longitude, station_carteasting, station_cartnorthing, stationparameter_name&format=html

N.B. not all components are necessarily required - if the results don't need filtered by the function's arguments, and the default return fields and format are sufficient, these may be omitted - a minimum query comprises:
 - the API root URL,
 - the back-end configuration,
 - and a query function.

Building a specific query function

In order to return a targeted subset of the data exposed by an API query function, the results are filtered, the required data-fields specified, and the return format selected, by careful specification of the function's arguments.

The function arguments fall into three groups - it may help to envisage a table of data comprising a number of columns of data types, each of which describes some element of the entry, with any number of rows of corresponding data values:

1. Query arguments : these typically filter the returned data - analogous to selecting specific rows in the table.
2. Return fields : these specify which data fields to return - analogous to choosing only particular table columns.
   
   • the return fields fall into two further types:
     1. listable named fields
     2. parameterised fields that take a variable argument
3. Return formats : these specify the resulting file or data format of the query

The following query examples are used to filter rows and select columns from the data in the table below - the query arguments and return fields are highlighted; the rows and columns of the returned example data are listed:

N.B. each query function takes a specific range of arguments - many are common across most or all functions, but - importantly - not all arguments are valid for a particular query. Refer to the built-in documentation for details.

Metadata

Metadata can be returned by specifying a comma-separated list of returnfields as part of an API query. Again, refer to the built-in documentation for the definitive list of valid metadata fields available for each query function.

N.B. use md_returnfields, not returnfields, with the getTimeseriesValues request.

Certain metadata are stored as custom attributes: these are retrieved with ca_sta query argument in a metadata request. These are demonstrated for the getTimeseriesValues query.

A walk-through of a time series data request

As an introduction to some of the key query functions, and to exploring the structured data archive, it is instructive to work through the following steps:

1. Get a list of available stations
2. Get a list of available parameters at a selection of stations
3. Get a list of available time series for a specific station's specific parameter
4. Return time series data from a specific time series of a specific station's specific parameter
5. Return time series data in a graph

N.B. the new elements of each HTTP request introduced in the examples below are highlighted in bold type.

Get a list of available stations

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

N.B. just the first 10 stations are shown below.

Get a list of available parameters at a selection of stations

Example : Return parameter information, filtering the result to just stations with similar names :

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

Get a list of available time series for a specific station's specific parameter

The default fields returned by getTimeseriesList provide the time series ID, ts_id, for further specific data requests; to retrieve the time series path components we specify the required fields with the returnfields argument.

Example : Filter the list of time series by station, station_name, and parameter, stationparameter_name:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Auchinner&stationparameter_name=Rain

Example : Return the specific fields required to build the time series path, site_no, station_no, stationparameter_no, ts_shortname:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Auchinner&stationparameter_name=Rain&returnfields=site_no, station_no, stationparameter_no, ts_shortname, coverage&dateformat=yyyy-MM-dd HH:mm:ss

N.B.  including coverage in returnfields argument returns the extent of the available time series data - see available formats

Example : Return the time series path directly, with coverage timestamps without time : ts_path and coverage

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Auchinner&stationparameter_name=Rain&returnfields=ts_path, coverage&dateformat=yyyy-MM-dd

Return time series data from a specific time series of a specific station's specific parameter

The next two queries return the same data: the last data record for the rainfall day total time series from Auchinner.

Example : the last data record for the rainfall day total by time series ID, ts_id

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

Example : the last data record for the rainfall day total by time series path, site_no/station_no/stationparameter_no/ts_shortname :

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_path=1/14964/RE/HDay.Total

N.B. site_no is always 1.

Whilst the default last value is useful, to return a specific period of data we specify date and/or duration, and to retrieve the data quality we use the returnfields argument:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=55572010&from=2021-10-12T09:00:00&period=P15D&returnfields=Timestamp, Value, Quality Code

N.B. be sure to return and understand quality coded data for any professional applications, particularly if being used to support decision-making - seek advice from SEPA if unsure about the suitability of the data, via hydrometry-requests@sepa.org.uk

Return data in a graph

The day total data, above, suggest that the period around the 23rd October might be of interest, so let's look at 3 days of 15-minute data from midday on the 22nd:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&ts_id=55570010&from=2021-10-22T12:00:00&period=P3D&format=png

N.B. The 0.2mm resolution of the observed data is apparent in the stepped trace.

And let's see how the river reacted over the same period. First, get the time series ID, ts_id, for Auchinner's 15-minute river level time series:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Auchinner&stationparameter_name=Level&ts_name=15*

Next, include the river level time series data in the getGraph query:

https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&ts_id=55570010,55579010&from=2021-10-22T12:00:00&period=P3D&format=png

N.B. return multiple time series in a single query by specifying a comma-separated list of ts_id.

A selection of more detailed query examples are described in the API endpoint examples section