Skip to main content

A Python 3, asyncio-based library for the ReCollect Waste API

Project description

🗑 aiorecollect: A Python 3 Library for Pinboard

CI PyPI Version License Code Coverage Maintainability

Buy Me A Coffee

aiorecollect is a Python 3, asyncio-based library for the ReCollect Waste API. It allows users to programmatically retrieve schedules for waste removal in their area, including trash, recycling, compost, and more.

Special thanks to @stealthhacker for the inspiration!


pip install aiorecollect

Python Versions

aiorecollect is currently supported on:

  • Python 3.10
  • Python 3.11
  • Python 3.12

Place and Service IDs

To use aiorecollect, you must know both your ReCollect Place and Service IDs.

In general, cities/municipalities that utilize ReCollect will give you a way to subscribe to a calendar with pickup dates. If you examine the iCal URL for this calendar, the Place and Service IDs are embedded in it:



import asyncio
from datetime import date

from aiorecollect import Client

async def main() -> None:
    client = await Client("<PLACE ID>", "<SERVICE ID>")

    # The client has a few attributes that you can access:

    # Get all pickup events on the calendar:
    pickup_events = await client.async_get_pickup_events()

    # ...or get all pickup events within a certain date range:
    pickup_events = await client.async_get_pickup_events(
        start_date=date(2020, 10, 1), end_date=date(2020, 10, 31)

    # ...or just get the next pickup event:
    next_pickup = await client.async_get_next_pickup_event()

The PickupEvent Object

The PickupEvent object that is returned from the above calls comes with three properties:

  • date: a that denotes the pickup date
  • pickup_types: a list of PickupType objects that will occur with this event
  • area_name: the name of the area in which the event is occurring

The PickupType Object

The PickupType object contains the "internal" name of the pickup type and a human-friendly representation when it exists:

  • name: the internal name of the pickup type
  • friendly_name: the humany-friendly name of the pickup type (if it exists)

Connection Pooling

By default, the library creates a new connection to ReCollect with each coroutine. If you are calling a large number of coroutines (or merely want to squeeze out every second of runtime savings possible), an aiohttp ClientSession can be used for connection pooling:

import asyncio

from aiohttp import ClientSession

from aiorecollect import Client

async def main() -> None:
    async with ClientSession() as session:
        client = await Client("<PLACE ID>", "<SERVICE ID>", session=session)

        # Get to work...


Thanks to all of our contributors so far!

  1. Check for open features/bugs or initiate a discussion on one.
  2. Fork the repository.
  3. (optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
  4. (optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
  5. Install the dev environment: script/setup
  6. Code your new feature or bug fix on a new branch.
  7. Write tests that cover your new functionality.
  8. Run tests and ensure 100% code coverage: poetry run pytest --cov aiorecollect tests
  9. Update with any new documentation.
  10. Submit a pull request!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aiorecollect-2023.11.0.tar.gz (6.7 kB view hashes)

Uploaded source

Built Distribution

aiorecollect-2023.11.0-py3-none-any.whl (6.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page