Package: uk-bin-collection
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 do this?
You might want to use this in a 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 ofBeautiful Soup 4to scrape data, although others use different approaches, such as emulating web browser behaviour, or reading data from CSV files.Home Assistant UsageInstall with HACS (recommended)Ensure you haveHACSinstalledIn the Home Assistant UI go toHACS>Integrations>⋮>Custom repositories.Enterhttps://github.com/robbrad/UKBinCollectionDatain theRepositoryfield.SelectIntegrationas the category then clickADD.Click+ Add Integrationand search for and selectUK Bin Collection Datathen clickDownload.Restart your Home Assistant.In the Home Assistant UI go toSettings>Devices & Servicesclick+ Add Integrationand search forUK Bin Collection Data.If your 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 seperately such asstandalone-chrome.Install manuallyOpen the folder for your Home Assistant configuration (where you findconfiguration.yaml).If you do not have acustom_componentsfolder there, you need to create it.Downloadthis repository then copy the foldercustom_components/uk_bin_collectioninto thecustom_componentsfolder you found/created in the previous step.Restart your Home Assistant.In the Home Assistant UI go toSettings>Devices & Servicesclick+ Add Integrationand search forUK Bin Collection Data.Standalone UsagePS 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)QuickstartThe basic command to execute a script is:python collect_data.py <council_name> "<collection_url>"wherecouncil_nameis the name of the council's .py script (without the .py) andcollection_urlis the URL to scrape.
The help documentation refers to these as "module" and "URL", respectively. Supported council scripts can be found in theuk_bin_collection/uk_bin_collection/councilsfolder.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 41Apostcodecan 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).Ahouse numbercan be passed with-n numberor--number number.AUPRN referencecan be passed with-u uprnor--uprn uprn.To check the parameters needed for your council's script, please check theproject wikifor more information.Project dependenciesSome scripts rely on external packages to function. A list of required scripts for both development and execution can be found in the project'sPROJECT_TOMLInstall can be done viapoetry installfrom within the root of the repo.UPRN FinderSome councils make use of the UPRN (Unique property reference number) to identify your property. You can find yourshereorhere.Requesting your councilTo make a request for your council, first check theIssuespage to make sure it has not already been requested. If not, please fill in a newCouncil Requestform, including as much information as possible, including:Name of the councilURL to bin collectionsAn example postcode and/or UPRN (whichever is relevant)Any further informationPlease 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 will get a script.Reports3.103.11Docker API ServerWe have created an API for this located underuk_bin_collection_api_serverPrerequisitesDocker installed on your machinePython (if you plan to run the API locally without Docker)Running the API with DockerClone this repository.Navigate to the uk_bin_collection_api_server directory of the project.Build the Docker Containerdockerbuild-tukbc_api_server.docker run -p 8080:8080 ukbc_api_serverAccessing the APIOnce the Docker container is running, you can access the API endpoints:API Base URL: http://localhost:8080/api
Swagger UI: http://localhost:8080/api/ui/API DocumentationThe API documentation can be accessed via the Swagger UI. Use the Swagger UI to explore available endpoints, test different requests, and understand the API functionalities.API EndpointsGET /bin_collection/{council}Description: Retrieves information about bin collection for the specified council.Parameters:council (required): Name of the council.
Other optional parameters: [Specify optional parameters if any]Example Request:curl-XGET"http://localhost:8080/api/bin_collection/{council}"-H"accept: application/json"Docker ComposeThis includes the Selenium standalone-chrome for Selenium based councilsversion: '3'

services:
  ukbc_api_server:
    build:
      context: .
      dockerfile: Dockerfile 
    ports:
      - "8080:8080"  # Adjust the ports as needed
    depends_on:
      - selenium

  selenium:
    image: selenium/standalone-chrome:latest
    ports:
      - "4444:4444"Run withsudoapt-getupdate
sudoapt-getinstalldocker-compose

docker-composeupFAQI've got an issue/support question - what do I do?Please post in theHomeAssistant threador raise a new (non council request)issue.I'd like to contribute, where do I start?Contributions are always welcome! SeeCONTRIBUTING.mdto get started. Please adhere to the project'scode of conduct.If you're new to coding/Python/BeautifulSoup, feel free to checkherefor issues that are good for newcomers!If you would like to try writing your own scraper, feel free to fork this project and use existing scrapers as a base for your approach (orcouncilclasstemplate.py).Contributors