1. Home
  2. API documentation
  3. API function reference

Back to API function reference

  • API function reference
  • Who we are

Principal query functions

These functions satisfy the majority of common use cases

Table of contents
Select a section to jump to:

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. 

Applicable return formats:

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

getStationList

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

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

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

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.

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

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.

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.

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!

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.

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

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 

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.

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.

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

Applicable formats:

  • jpg
  • png