After recent flooding due to the winter storms I had another look at the SEPA data as I have already used the website with its graphs of river level and had seen that there was previously a file download containing the most recent river levels.
This time when I started looking at it I found that there is a BETA API to access a lot of different data sets from monitoring stations across Scotland.
https://timeseriesdoc.sepa.org.uk/api-documentation/
From the documentation I found there is a free mode although there is a daily limit on the number of requests you can make before it will block further calls. At the moment I am not sure how many requests this is but it made me look at how I might be able to return multiple values with a single call instead of making multiple calls.
If you exceed the daily limit then you can register for an API key but this requires OAuth2.0 and the API calls need an access token that are valid for 24 hours so I think it would require a specific component or integration instead of being able to use the existing rest sensor platform.
What I wanted to do was have a dashboard that would display the river as a graph so I could see the trend and identify when it was getting close to a level I knew would flood locally.
I followed the steps below to get the appropriate ts_id for the data I was interested in.
-
List all the parameters from all the stations so that you can decide
which stations and dataset you are interested in. This works from a
browser so it probably the best starting pointhttps://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getstationlist&returnfields=station_no,station_name,stationparameter_name,stationparameter_no,catchment_id,catchment_no,catchment_name,station_latitude,station_longitude,station_carteasting,station_cartnorthing,river_id,river_name,ca_sta&ca_sta_returnfields=CATCHMENT_SIZE,GAUGE_DATUM,GROUND_DATUM,GWREF_DATUM&object_type=General -
If you take the station_name you are interested in, in this case Peebles, and enter it in the query below you list all the time series available for that Station
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesList&station_name=Peebles -
In the return data there may be some duplicate names with different ts_id (e.g. 15minute) but if you loo there should be a different parametertype_name. I have found that the values are as below but there may be more
- Q = Flow
- S = Level
-
We are interested in the 15minute river Level so we choose ts_id 55822010 and using the query below we can get the single value in JSON format
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=55822010&returnfields=Value&format=json -
We can now use this to get the data for a single station but I was interested in multiple values from all the stations upstream from my location but we can actually do this with a single query by providing multiple ts_id values as a comma separated list in the query
https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=55822010,55790010,59631010,55717010&returnfields=Value&format=json -
This returns the following JSON
[ {"ts_id": "59631010","rows": "1","columns":"Value", "data": [[0.223]]}, {"ts_id": "55822010","rows": "1","columns":"Value", "data": [[1.075]]}, {"ts_id": "55717010","rows": "1","columns":"Value", "data": [[0.539]]}, {"ts_id": "55790010","rows": "1","columns":"Value", "data": [[0.535]]} ] -
It is then possible to use the rest sensor platform and take the value from a single API call and then use it to set multiple sensor values in the configuration.yaml file
rest: - resource: https://timeseries.sepa.org.uk/KiWIS/KiWIS?service=kisters&type=queryServices&datasource=0&request=getTimeseriesValues&ts_id=55822010,55790010,59631010,55717010&returnfields=Value&format=json scan_interval: 3600 sensor: - name: "Peebles SEPA River Level" value_template: > {% set item = value_json | selectattr('ts_id','eq',"55822010") | list | first %} {{ item.data[-1][-1] }} unit_of_measurement: "m" - name: "March Street SEPA River Level" value_template: > {% set item = value_json | selectattr('ts_id','eq',"55790010") | list | first %} {{ item.data[-1][-1] }} unit_of_measurement: "m" - name: "Glenbreck SEPA River Level" value_template: > {% set item = value_json | selectattr('ts_id','eq',"59631010") | list | first %} {{ item.data[-1][-1] }} unit_of_measurement: "m" - name: "Kingledores SEPA River Level" value_template: > {% set item = value_json | selectattr('ts_id','eq',"55717010") | list | first %} {{ item.data[-1][-1] }} unit_of_measurement: "m"
Once we have the sensor value I created a dashboard with a graph and a gauge so that I could see the trend over time as well as a gauge that would highlight in one colour when the level got close to the flood level and another when it went over.
Using the following in a lovelace dashboard you can show a graph and a gauge based on the max and min values that are also available through the API but I took them from the website
title: Home
views:
- path: default_view
title: Home
cards:
- type: gauge
min: 0
max: 3.5
entity: sensor.peebles_sepa_river_level
severity:
green: 0
yellow: 2.5
red: 2.5
- type: history-graph
entities:
- entity: sensor.peebles_sepa_river_level
hours_to_show: 36
refresh_interval: 0
SEPA Website to get the levels for the gauge
https://www2.sepa.org.uk/waterlevels/default.aspx?sd=t&lc=14979
These values could be used to trigger any form of automation you wanted as normal.
