BinDays-API

BinDays-App • BinDays-Client • BinDays-API • BinDays-HomeAssistant

Have a question or a problem? Check the Frequently Asked Questions before opening an issue.

Overview

BinDays-API is the server-side component for the BinDays project. It provides the logic and configuration for retrieving bin collection schedules from UK councils.

It works with a client application (BinDays-App, BinDays-Client) to fetch data.

How It Works

The API doesn't scrape councils directly. Instead, it generates request configurations (URLs, headers, payloads) and sends them to a client. The client executes the HTTP request and sends the raw response back to the API for processing.

This approach has a few benefits:

• Avoids IP Blocking: Council requests come from the user's IP, not a server, which avoids blocks, rate-limiting, and CAPTCHAs.
• Dynamic Updates: Collector logic can be updated server-side without requiring a client app update.
• Stateless & Lightweight: The API is stateless with no external dependencies.

Deployment

The API is containerized for deployment with Docker.

Run the Public Image

Deploy the pre-built image from the GitHub Container Registry:

docker run -d \
    --name bindays-api \
    -p 8080:8080 \
    ghcr.io/badgerhobbs/bindays-api:latest

Build from Source

Build the Docker image locally:

docker build -t bindays-api:latest .

Contributing

To add a council, fix a bug, or improve the project, see the Contributing Guidelines. For questions, check the FAQs.

License

This project is licensed under the AGPL-3.0 License.

Support

If you find this project helpful, please consider supporting its development.