API function reference

Table of contents
Select a section to jump to:

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

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 - this is fixed and specific to 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

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

Query	Returned data
	Rows	Columns
What stations measure rain and level, and what catchments are they in?
getStationList &stationparameter_no= RE, SG &returnfields= station_no, catchment_name &flatten=true	1,4,8,9	B,D
What stations are in the Tay catchment and what rivers are they on?
getStationList &catchment_name= Tay &returnfields= station_name, station_no, river_name &flatten=true	2,4,7,8,10	A,B,E
What parameters are observed at stations with a 'u' in their names?
getStationList &station_name= *u* &returnfields= station_name, stationparameter_name &flatten=true	1,3,10	A,C

	A	B	C	D	E
	station_name	station_no	stationparameter_no	catchment_name	river_name
1	Auchinner	14964	RE;SG	Earn	Allt Srath a Ghlinne
2	Balmacneil	14938	SG	Tay	Tay
3	Cultybraggan	14965	Q;SG	Earn	Ruchill Water
4	Dalnamein	14960	RE;SG	Tay	Garry(Tayside)
5	Forteviot Bridge	14970	Q;SG	Earn	Earn
6	Glen Ample	335475	RE	Earn
7	Hermitage	8402	Q;SG	Tay	Braan
8	Killin	14933	RE;Q;SG	Tay	Tay
9	Kinkell Bridge	14968	RE;Q;SG	Earn	Earn
10	Luncarty	14940	Q;SG	Tay	Ordie Burn

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.

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

---

Get a list of available stations

---

Get a list of available parameters at a selection of stations

---

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.

---

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.

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:

---

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:

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:

---

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