Specifying date and time
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.
Table of contents
Select a section to jump to:
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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&metadata=true&returnfields=Timestamp, 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
where:
- 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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&metadata=true&returnfields=Timestamp, 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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&metadata=true&returnfields=Timestamp, Value, Quality Code&ts_path=1/4638/Q/15m.Cmd&from=2006-12-13T22:30:00&to=2006-12-14T18:30:00&format=png
Period
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.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&metadata=true&returnfields=Timestamp, Value, Quality Code×eriesgroup_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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&metadata=true&returnfields=Timestamp, 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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getGraph&metadata=true&returnfields=Timestamp, 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
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&metadata=true&returnfields=Timestamp, 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.
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&metadata=true&returnfields=Timestamp, Value, Quality Code&ts_path=1/*/RE/15m.Total&dateformat=yyyy-MM-dd'T'HH:mm:ss
Supported formats:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX
yyyy-MM-dd'T'HH:mm:ssXXX
yyyy-MM-dd HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd HH:mm:ss
yyyy-MM-dd
yyyy-MM
yyyy
yyyy-MM-ddXXX
yyyyXXX
yyyy-MMXXX
UNIX (in milliseconds)