Add a WaterCompany class for Scottish Water

[AlexLipp]

In POOPy, each water company in the UK is represented by a subclass of the WaterCompany super-class. For instance the AnglianWater module. Each sub-class accesses the different API that is provided by that water company that allows access to their near real time event duration monitoring data. However, in many ways, they are very similar. All the water companies are available here.

Scottish Water have now released an API for their event duration monitoring data here. Add a new module to the companies which creates a new subclass called ScottishWater which interacts with the API just like the other sub-classes.

The details of the API are copied below:

Overview

Scottish Water’s Overflow Map provides near real-time data on monitored sewer overflows across Scotland.

We are being open and transparent, sharing our data exactly as we receive it, and have provided a public Application Programme Interface (API) that allows you to access and reuse this data in your application.

What the Near Real-time Overflow Map Shows
Our Overflow Map shows the locations of overflows on the Scottish Water network with Event Duration Monitoring (EDM).

It provides near real-time information on monitor activations and is updated every 60 minutes. However, not all the overflows record data and update data at the same frequency.

EDM monitors do not confirm overflow events, they only indicate them. There may be times when errors occur, e.g. due to maintenance activity or movement close to the monitor, indicating the overflow is active, when it isn’t.

We can’t say there has been any pollution or promise the water is safe to swim in. Our information can help water users make more informed decisions, but this data is not advice on water quality.

The EDM monitors will indicate:

• an overflow is currently occurring or has occurred in the last 48 hours
• the total duration of overflow events in the last 48 hours
• the date and time of the most recent and previous overflow events
• the priority for planned future investment
• For each EDM monitored location that we have overflow data indicating Overflowing or No Overflow we provide the most recent 48 hours of rainfall in mm. EDM monitors in Recent Overflow status present the 48 hour period before that overflow stopped.

About the API

The Near Real Time (NRT) Application Programme Interface (API) allows users to connect to our Near Real Time (NRT) Overflow Map data. The API can be used to integrate this data into your application.

How to Use the NRT API

Access

The API is open for public use. No authentication is required, but users should respect rate limits and cache data where possible.

Servers

https://api.scottishwater.co.uk/overflow-event-monitoring/v1

Endpoints

GET: https://api.scottishwater.co.uk/overflow-event-monitoring/v1/near-real-time

Responses:

200: Successful response
Content: application/json

Example: 
{
 "results": {
    "OVERFLOW_START_DATETIME_PREVIOUS": "2025-08-09T07:28:43.000Z",
    "OVERFLOW_END_DATETIME_PREVIOUS": "2025-08-09T08:04:56.000Z",
    "OVERFLOW_DURATION_MIN_PREVIOUS": 36.22,
    "OVERFLOW_START_DATETIME": "2025-08-10T22:13:22.000Z",
    "OVERFLOW_END_DATETIME": "2025-08-10T23:02:05.000Z",
    "OVERFLOW_DURATION_MIN": 48.72,
    "OVERFLOW_STATUS_ID": 15,
    "OVERFLOW_STATUS_DESCRIPTION": "NO - No Overflows",
    "ASSET_ID": "CSO001446",
    "ASSET_NAME": "WISHAW PLAYING FIELD PCSO NS795566",
    "LICENCE_NUMBER": "CAR/L/1026132",
    "SW_UNIQUE_MEASUREMENT_POINT_DESCRIPTION": "Wishaw, Playing Field CSO Event",
    "OVERFLOW_TYPE": "CSO",
    "RECEIVING_WATER": "South Calder Water",
    "DISCHARGE_OVERFLOW_LOCATION_GRID_REFERENCE": "NS 79568 56663",
    "DISCHARGE_OVERFLOW_LOCATION_POSTCODE": "ML2 7LD",
    "DISCHARGE_OVERFLOW_LOCATION_X": 279568,
    "DISCHARGE_OVERFLOW_LOCATION_Y": 656663,
    "DISCHARGE_OVERFLOW_LOCATION_LATITUDE": 55.788221,
    "DISCHARGE_OVERFLOW_LOCATION_LONGITUDE": -3.9221516,
    "LOCAL_AUTHORITY_NAME": "North Lanarkshire",
    "INVESTMENT_PRIORITY": "None",
    "IS_INVESTMENT_DRIVER_AESTHETIC": false,
    "IS_INVESTMENT_DRIVER_WATER_QUALITY": false,
    "IS_INVESTMENT_DRIVER_OPERATING_IN_DRY_WEATHER": false,
    "IS_INVESTMENT_DRIVER_EMERGENCY_STORAGE": false,
    "TOTAL_OVERFLOWS_DURATION_MIN_PAST_48_HRS": null,
    "LAST_TRANSMITTED_DATETIME": "2025-08-13T20:05:36.000Z",
    "DEVICE_LAST_TRANSMITTED_DATETIME": "2025-08-14T06:04:08.930Z",
    "INTERNAL_OVERFLOW_STATUS_ID": "18",
    "RAINFALL_HISTORY": ""
     }
}

401: Incorrect key: only applicable when using an API key. If you experience this using the public API, please contact us.

500: An unexpected error occurred. If you experience this using the public API, please contact us.

This API data includes "OVERFLOW_STATUS_ID" which relate to the 4 current overflow statuses as follows:
13 - Overflowing
14 - Recent Overflow
15 - No Overflows
16 - No Data Available
Instances where "OVERFLOW_STATUS_ID" = 16 (No Data Available) then the field "INTERNAL_OVERFLOW_STATUS_ID" provides additional insight as follows:

17 - No data received in the past 48 hours
18 - No valid data received in the past 48 hours
19 - Under Maintenance
20 - Non real-time monitored
21 - Non Active Device
A Note on Dates and Times
The data on the NRT Overflow Map on our website is in UK local time.
The data available via the NRT API is in Coordinated Universal Time (UTC).
Terms of Use
Other overflow maps may use different icons, colours, descriptions, and statuses. We are not responsible for how third parties may reuse our data. For accuracy, we advise you to refer to the data presented on the official Scottish Water website.

Data is provided under an open license for reuse.
Scottish Water is not liable for third-party interpretations.
Users must cite Scottish Water as the data source.