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

Specifying date and time

Specify the temporal extent of returned time series data and the formats of timestamps

Specific data and time formats are used in both specifying the time series data to be returned and in specifying the format of the returned data.

Last value

By default, requests made with the getTimeseriesValues and getGraph query functions return just the last data record.

Example :  last value for all level time series, Value, Quality Code&ts_path=1/*/SG/15m.Cmd

There are three query arguments that allow a more specific period to be returned, and these may be used alone or in conjunction; they are:

  • from
  • to
  • period
N.B. getTimeseriesValueLayer is a special case in which only a single value is returned per time series. This is the last value, or the value most recent to a timestamp specified by the date argument.

Date, time and duration formats

The date, from, and to arguments are specified with a timestamp, in the format:

yyyy-MM-ddTHH:mm:ss or yyyy-MM-dd


  • yyyy is the year,
  • MM is the month,
  • dd is the day,
  • HH the hour, as 24h,
  • mm, the minute and
  • ss the second.

If the hour, minute, and second are omitted then the time 00:00:00 is applied.

The period argument is specified in terms of an integer value and key letter representing a unit of time, prefixed by P. Multiple values and keys may be strung together, but must be in descending order of duration. The recognised keys are:

  • Y = Year
  • M = Month
  • D = Day

Periods shorter than a day are additionally prefixed by T

  • H = Hour
  • M = Minute
  • S = Second

In addition, W = Week, but is mutually exclusive of the D (day) setting

Finally, period may be specified with the keyword complete, which returns the entire record.

N.B. take care to avoid using period=complete with high resolution data, i.e. 15-minute and hourly values, as this may return extremely large quantities of data, and is likely to exceed the configured maximum or seriously deplete your download credit.
Examples: P3D, P1Y, P1DT12H, PT6H, P1Y6M3DT4H20M30S, P1W

From and To

From and to are used to define specific endpoints; if used alone, from returns data until the end of the record, and to returns data from the start of the record.

Example, using specific date, without specifying time : a month's hourly rainfall totals

Aggregated rainfall observations at Edinburgh Royal Botanical Gardens for July 2021, Value, Quality Code&ts_path=1/15201/RE/Hour.Total&from=2021-07-01&to=2021-07-31&format=png
Example, using specific date and time : 15-minute flow for 20 hours about a peak

Peak event on the Forth at Craigforth, station_no 4638, 2006-12-14 08:30, Value, Quality Code&ts_path=1/4638/Q/15m.Cmd&from=2006-12-13T22:30:00&to=2006-12-14T18:30:00&format=png


If the period argument is specified alone it extends the default 'last value' condition to return the specified duration up to and including the last value.

Example : A fortnight's daily rainfall up to 'today' for a time series group (find available time series groups using getGroupList).

For daily rainfall data the last value will be 'yesterday' at 09:00 since the data for 'today' is not complete., Value, Quality Code&timeseriesgroup_id=279952&period=P2W

Period with From or Period with To

Combining the from with period or period with to query arguments provides a neat way of returning specific periods of data without the need to determine both from and to timestamps.

Example 15 minute flow data from Craigforth as above, but using the period argument, Value, Quality Code&ts_path=1/4638/Q/15m.Cmd&from=2006-12-13T22:30:00&Period=PT20H
Example : Mean daily groundwater level at Aldern Junction for 1 year to 30th September 2015, Value, Quality Code&ts_path=1/300348/GWL/CDay.Mean&to=2015-09-30&period=P1Y&format=png

Period Complete

Period complete is a request for all the data in a time series.  For most high resolution time series this will request be too many data values and will be refused.  For daily values the request can typically be used for 5 or more time series and for monthly values it will be possible to request the data for all time series of a parameter.

Example : Complete daily mean flow record for the Tay at Ballathie, Value, Quality Code&ts_path=1/14937/Q/HDay.Mean&period=complete

Setting the return date format

The format of returned timestamps is specified with dateformat argument to a query function., Value, Quality Code&ts_path=1/*/RE/15m.Total&dateformat=yyyy-MM-dd'T'HH:mm:ss

Supported formats:

yyyy-MM-dd HH:mm:ss.SSS
yyyy-MM-dd HH:mm:ss
UNIX (in milliseconds)