Add City of Ballarat, Australia (#1567)

* Add City of Ballarat, Australia

Add source for City of Ballarat, Australia via API.

- Add source/ballarat_vic_gov_au
- Add ballarat_vic_giv_au.md
- Update info.md
- Update README.md

* refactor to remove duplicate code

---------

Co-authored-by: 5ila5 <5ila5@users.noreply.github.com>

README.md

@@ -33,6 +33,7 @@ Waste collection schedules in the following formats and countries are supported.
 - [Brisbane City Council](/doc/source/brisbane_qld_gov_au.md) / brisbane.qld.gov.au
 - [Campbelltown City Council (NSW)](/doc/source/campbelltown_nsw_gov_au.md) / campbelltown.nsw.gov.au
 - [Cardinia Shire Council](/doc/source/cardinia_vic_gov_au.md) / cardinia.vic.gov.au
+- [City of Ballarat](/doc/source/ballarat_vic_gov_au.md) / ballarat.vic.gov.au
 - [City of Canada Bay Council](/doc/source/canadabay_nsw_gov_au.md) / canadabay.nsw.gov.au
 - [City of Greater Geelong](/doc/source/geelongaustralia_com_au.md) / geelongaustralia.com.au
 - [City of Kingston](/doc/source/kingston_vic_gov_au.md) / kingston.vic.gov.au

custom_components/waste_collection_schedule/waste_collection_schedule/source/ballarat_vic_gov_au.py

@@ -0,0 +1,74 @@
+import logging
+from datetime import datetime
+
+import requests
+from waste_collection_schedule import Collection  # type: ignore[attr-defined]
+
+TITLE = "City of Ballarat"
+DESCRIPTION = "Source for City of Ballarat rubbish collection."
+URL = "https://www.ballarat.vic.gov.au"
+TEST_CASES = {
+    "Clothesline Cafe": {
+        "street_address": "202 Humffray Street South BAKERY HILL VIC 3350"
+    },
+    "Cuthberts Road Milk Bar": {
+        "street_address": "27 Cuthberts Road ALFREDTON VIC 3350"
+    },
+}
+
+_LOGGER = logging.getLogger(__name__)
+
+WASTE_NAMES = {
+    "waste": "General Waste",
+    "recycle": "Recycling",
+    "green": "Green Waste",
+}
+
+ICON_MAP = {
+    "waste": "mdi:trash-can",
+    "recycle": "mdi:recycle",
+    "green": "mdi:leaf",
+}
+
+
+class Source:
+    def __init__(self, street_address):
+        self._street_address = street_address
+
+    def fetch(self):
+        session = requests.Session()
+
+        response = session.get(
+            "https://data.ballarat.vic.gov.au/api/records/1.0/search/",
+            params={"dataset": "waste-collection-days", "q": self._street_address},
+        )
+        response.raise_for_status()
+        addressSearchApiResults = response.json()
+        if (
+            addressSearchApiResults["records"] is None
+            or len(addressSearchApiResults["records"]) < 1
+        ):
+            raise Exception(
+                f"Address search for '{self._street_address}' returned no results. Check your address on https://data.ballarat.vic.gov.au/pages/waste-collection-day/"
+            )
+
+        addressSearchTopHit = addressSearchApiResults["records"][0]
+        _LOGGER.debug("Address search top hit: %s", addressSearchTopHit)
+
+        entries = []
+        collection_dates = [
+            (key.replace("next", ""), val)
+            for key, val in addressSearchTopHit["fields"].items()
+            if key.startswith("next")
+        ]
+        for collection_type, collection_date in collection_dates:
+            date = datetime.strptime(collection_date, "%Y-%m-%d").date()
+            entries.append(
+                Collection(
+                    date=date,
+                    t=WASTE_NAMES.get(collection_type, collection_type),
+                    icon=ICON_MAP.get(collection_type, "mdi:trash-can"),
+                )
+            )
+
+        return entries

doc/source/ballarat_vic_gov_au.md

@@ -0,0 +1,32 @@
+# City of Ballarat
+
+Support for schedules provided by [City of Ballarat](https://data.ballarat.vic.gov.au/pages/waste-collection-day/).
+
+## Configuration via configuration.yaml
+
+```yaml
+waste_collection_schedule:
+  sources:
+    - name: ballarat_vic_gov_au
+      args:
+        street_address: STREET_ADDRESS
+```
+
+### Configuration Variables
+
+**street_address**  
+*(string) (required)*
+
+## Example
+
+```yaml
+waste_collection_schedule:
+  sources:
+    - name: ballarat_vic_gov_au
+      args:
+        street_address: 202 Humffray Street South BAKERY HILL VIC 3350
+```
+
+## How to get the source arguments
+
+Visit the [City of Ballarat waste collection calendar](https://data.ballarat.vic.gov.au/pages/waste-collection-day/) page and search for your address. The arguments should exactly match the street address shown in the autocomplete result.