UK Bin Collection Data (UKBCD)

This project aims to provide a neat and standard way of providing bin collection data in JSON format from UK councils that have no API to do so.

Why would you want to do this? You might want to use this in Home Automation—for example, say you had an LED bar that lit up on the day of bin collection to the colour of the bin you want to take out; then this repo provides the data for that.

PLEASE respect a councils' infrastructure / usage policy and only collect data for your own personal use on a suitable frequency to your collection schedule.

Most scripts make use of Beautiful Soup 4 to scrape data, although others use different approaches, such as emulating web browser behaviour, or reading data from CSV files.

Requesting your council

:warning: Please check that a request for your council has not already been made. You can do this by searching on the Issues page.

If an issue already exists, please comment on that issue to express your interest. Please do not open a new issue, as it will be closed as a duplicate.

If an issue does not already exist, please fill in a new Council Request form, including as much information as possible, including:

Name of the council.
URL to bin collections.
An example postcode and/or UPRN (whichever is relevant).
Any further information.

Please be aware that this project is run by volunteer contributors and completion depends on numerous factors - even with a request, we cannot guarantee if/when your council is added to this integration.

Home Assistant Usage

Install with HACS (recommended)

Automated

This integration can be installed directly via HACS. To install:

Add the repository to your HACS installation
Click Download

For details on how to setup the custom component integration, see the documentation.

Manual

Ensure you have HACS installed
In the Home Assistant UI go to HACS > Integrations > ⋮ > Custom repositories.
Enter https://github.com/robbrad/UKBinCollectionData in the Repository field.
Select Integration as the category then click ADD.
Click + Add Integration and search for and select UK Bin Collection Data then click Download.
Restart your Home Assistant.
In the Home Assistant UI go to Settings > Devices & Services click + Add Integration and search for UK Bin Collection Data.
If you see a "URL of the remote Selenium web driver to use" field when setting up your council, you'll need to provide the URL to a web driver you've set up separately such as standalone-chrome.

Install manually

Open the folder for your Home Assistant configuration (where you find configuration.yaml).
If you do not have a custom_components folder there, you need to create it.
Download this repository then copy the folder custom_components/uk_bin_collection into the custom_components folder you found/created in the previous step.
Restart your Home Assistant.
In the Home Assistant UI go to Settings > Devices & Services click + Add Integration and search for UK Bin Collection Data.

Overriding the Bin Icon and Bin Colour

We realise it is difficult to set a colour from the councils text for the Bin Type and to keep the integration generic, we don't capture colour from a council (not all councils supply this as a field), only bin type and next collection date.

When you configure the component on the first screen, you can set a JSON string to map the bin type to the colour and icon

Here is an example to set the colour and icon for the type Empty Standard General Waste. This type is the type returned from the council for the bin. You can do this for multiple bins.

If you miss this on the first setup, you can reconfigure it.

{     
  "Empty Standard General Waste": 
  {         
    "icon": "mdi:trash-can",         
    "color": "blue"     
  }
}

Standalone Usage

PS G:\Projects\Python\UKBinCollectionData\uk_bin_collection\collect_data.py
usage: collect_data.py [-h] [-p POSTCODE] [-n NUMBER] [-u UPRN] module URL

positional arguments:
  module                Name of council module to use                           (required)
  URL                   URL to parse                                            (required)

options:
  -h, --help                            show this help message                  (optional)
  -p POSTCODE, --postcode POSTCODE      Postcode to parse - should include      (optional)
                                        a space and be wrapped in double
                                        quotes                                  
  -n NUMBER, --number NUMBER            House number to parse                   (optional)
  -u UPRN, --uprn UPRN                  UPRN to parse                           (optional)

Quickstart

The basic command to execute a script is:

python collect_data.py <council_name> "<collection_url>"

where council_name is the name of the council's .py script (without the .py) and collection_url is the URL to scrape. The help documentation refers to these as "module" and "URL", respectively. Supported council scripts can be found in the uk_bin_collection/uk_bin_collection/councils folder.

Some scripts require additional parameters, for example, when a UPRN is not passed in a URL, or when the script is not scraping a web page. For example, the Leeds City Council script needs two additional parameters—a postcode, and a house number. This is done like so:

python collect_data.py LeedsCityCouncil https://www.leeds.gov.uk/residents/bins-and-recycling/check-your-bin-day -p "LS1 2JG" -n 41

A postcode can be passed with -p "postcode" or --postcode "postcode". The postcode must always include a space in the middle and be wrapped in double quotes (due to how command line arguments are handled).
A house number can be passed with -n number or --number number.
A UPRN reference can be passed with -u uprn or --uprn uprn.

To check the parameters needed for your council's script, please check the project wiki for more information.

Project dependencies

Some scripts rely on external packages to function. A list of required scripts for both development and execution can be found in the project's [PROJECT_TOML](https://github.c

UKBinCollectionData

Install / Use

README