add St Albans, UK

README.md

@@ -1443,6 +1443,7 @@ Waste collection schedules in the following formats and countries are supported.
 - [South Somerset District Council](/doc/source/iweb_itouchvision_com.md) / somerset.gov.uk
 - [South Tyneside Council](/doc/source/southtyneside_gov_uk.md) / southtyneside.gov.uk
 - [Southampton City Council](/doc/source/southampton_gov_uk.md) / southampton.gov.uk
+- [St Albans City & District Council](/doc/source/stalbans_gov_uk.md) / stalbans.gov.uk
 - [Stafford Borough Council](/doc/source/staffordbc_gov_uk.md) / staffordbc.gov.uk
 - [Stevenage Borough Council](/doc/source/stevenage_gov_uk.md) / stevenage.gov.uk
 - [Stirling.gov.uk](/doc/source/stirling_uk.md) / stirling.gov.uk

custom_components/waste_collection_schedule/sources.json

@@ -7641,6 +7641,11 @@
       "module": "southampton_gov_uk",
       "default_params": {}
     },
+    {
+      "title": "St Albans City & District Council",
+      "module": "stalbans_gov_uk",
+      "default_params": {}
+    },
     {
       "title": "Stafford Borough Council",
       "module": "staffordbc_gov_uk",

custom_components/waste_collection_schedule/waste_collection_schedule/source/stalbans_gov_uk.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+
+import requests
+from waste_collection_schedule import Collection  # type: ignore[attr-defined]
+
+TITLE = "St Albans City & District Council"
+DESCRIPTION = "Source for St Albans City & District Council."
+URL = "https://stalbans.gov.uk"
+TEST_CASES = {
+    "55 St John's Ct": {"uprn": 100081132201},
+    "9 Tyttenhanger Grn": {"uprn": "100080869141"},
+}
+
+
+ICON_MAP = {
+    "refuse": "mdi:trash-can",
+    "food": "mdi:food",
+    "garden": "mdi:leaf",
+    "recycling": "mdi:recycle",
+}
+
+
+API_URL = "https://gis.stalbans.gov.uk/NoticeBoard9/VeoliaProxy.NoticeBoard.asmx/GetServicesByUprnAndNoticeBoard"
+
+
+class Source:
+    def __init__(self, uprn: str | int):
+        self._uprn: str | int = uprn
+
+    def fetch(self) -> list[Collection]:
+        data = {"noticeBoard": "default", "uprn": self._uprn}
+        s = requests.Session()
+        r = s.post(API_URL, json=data)
+        r.raise_for_status()
+
+        data = r.json()
+        if (
+            not data
+            or not isinstance(data, dict)
+            or "d" not in data
+            or not isinstance(data["d"], list)
+        ):
+            raise ValueError("Got invalid response from API")
+
+        entries = []
+        for entry in data["d"]:
+            if not isinstance(entry, dict):
+                continue
+
+            if not "ServiceHeaders" or not isinstance(entry["ServiceHeaders"], list):
+                continue
+
+            for header in entry["ServiceHeaders"]:
+                if not isinstance(header, dict):
+                    continue
+
+                bin_type = header.get("TaskType")
+                if not bin_type or not isinstance(bin_type, str):
+                    continue
+                bin_type = bin_type.removeprefix("Collect ")
+                icon = ICON_MAP.get(
+                    bin_type.lower()
+                    .replace("domestic", "")
+                    .replace("communal", "")
+                    .replace("paid", "")
+                    .strip()
+                )
+                for date_key in ("Last", "Next"):
+                    date_str = header.get(date_key)
+                    if not date_str or not isinstance(date_str, str):
+                        continue
+                    date_str = date_str.split("T")[0]
+                    d = datetime.strptime(date_str, "%Y-%m-%d").date()
+                    entries.append(Collection(d, bin_type, icon))
+        return entries

doc/source/stalbans_gov_uk.md

@@ -0,0 +1,39 @@
+# St Albans City & District Council
+
+Support for schedules provided by [St Albans City & District Council](https://stalbans.gov.uk), serving St Albans, UK.
+
+## Configuration via configuration.yaml
+
+```yaml
+waste_collection_schedule:
+    sources:
+    - name: stalbans_gov_uk
+      args:
+        uprn: "UPRN"
+```
+
+### Configuration Variables
+
+**uprn**  
+*(String | Integer) (required)*
+
+## Example
+
+```yaml
+waste_collection_schedule:
+    sources:
+    - name: stalbans_gov_uk
+      args:
+        uprn: "100081132201"
+        
+```
+
+## How to get the source argument
+
+### Easy way (external website)
+
+An easy way to discover your Unique Property Reference Number (UPRN) is by going to <https://www.findmyaddress.co.uk/> and entering in your address details.
+
+### Hard way (browser developer tools)
+
+Goto <https://gis.stalbans.gov.uk/NoticeBoard9/NoticeBoard.aspx>, open your browser developer tools, goto the network tab and inspect the network requests as you select your address. You will see a POST request to `https://gis.stalbans.gov.uk/NoticeBoard9/VeoliaProxy.NoticeBoard.asmx/GetServicesByUprnAndNoticeBoard` you can find the UPRN in the request payload.