bachya / aiorecollect

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

🗑 aiorecollect: A Python 3 Library for Pinboard

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!

Installation

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:

webcal://recollect.a.ssl.fastly.net/api/places/PLACE_ID/services/SERVICE_ID/events.en-US.ics

Usage

import asyncio
from datetime import date

from aiorecollect import Client


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

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

    # 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()


asyncio.run(main())

The PickupEvent Object

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

• date: a datetime.date 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:
    """Run."""
    async with ClientSession() as session:
        client = await Client("<PLACE ID>", "<SERVICE ID>", session=session)

        # Get to work...


asyncio.run(main())

Contributing

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 README.md with any new documentation.
10. Submit a pull request!

aiorecollect's Issues

Recollect failing to get next pickup in home assistant

Describe the bug
I've been noticing that the integration in home assistant has been failing to fetch my pickups recently, after some digging I think the output has been changed on the api.recollect.net side.

Home assistant logging indicates that the call it is making is to https://api.recollect.net/api/places/561F80AC-DA9C-11E9-85F8-60C6F93C4E98/services/1110/events Which yields the following output on the date today 31 Aug 2023. It is lacking the details for my "tomorrow" pickup of 1 Sept 2023.

After poking around on my region's waste website and seeing the API calls the one that is returning true data that is useful is:
https://api.recollect.net/api/places/561F80AC-DA9C-11E9-85F8-60C6F93C4E98/services/1110/events\?nomerge\=1\&hide\=reminder_only\&after\=2023-08-27\&before\=2023-10-09 which yields the following output when queried on 31 Aug 2023

To Reproduce
Steps to reproduce the behavior:

1. Use home assistant with place and service IDs from the URLs above
2. Query the data (which may be time bound to 31 aug 2023 for the bug to show, although I've noticed this failing in recent weeks, I believe it is a data change on the api.recollect side)
3. Receive no data for the "next pickup" in home assistant.

Expected behavior
The "next pickup" to have data. Though I believe this is an API change on the recollect side.

Additional context
Happy to help debug, I want to try and get a patch together but that may take me some time due to family obligations.

I think the ?nomerge call with some date bounds may be needed. I think there's an edge case on end of month for the plain /events API to return valid data. I expect tomorrow morning on 1 Sept 2023 that the /events API may return useful information again. I will report back.

Missing friendly name for "hhw_collect"

Describe the bug
I'm currently using recollect waste via Home Assistant. Recently I've been noticing that my automations that used it are including a new pickup type "hhw_collect".

I'd like to get a friendly name into this if possible.

To Reproduce
Steps to reproduce the behavior:

1. Configure a location using place 740E04F6-D678-11E6-AAA5-549294E6FE1C and service id 323
2. Observe that future pickups have hhw_collect

Expected behavior
I was expecting that to be "Household Hazardous Waste" (which is described here: http://www.austintexas.gov/faq/what-items-are-accepted-recycle-reuse-drop-center#overlay-context=department/austin-resource-recovery/faq)

Screenshots

Additional context
Add any other context about the problem here.

Also store pickup subject

aiorecollect/aiorecollect/client.py

Line 91 in f51c5d0

pickup["name"]

(see stealthhacker/python-recollect-waste#3)

For my area, certain events have somewhat clunky names, but more useful subjects (city names redacted):

name	subject
Garbage	Garbage
MixedRecycle	Mixed recycling
GlassRecycle	Glass recycling
XXXXXXXXXXX_FoodYardDebris	Food and yard debris
leafXXXXXXXXX	Free Leaf Drop-off Event
rx	National Rx Drug Take Back Day
shredXXXXX	XXXXXXXXX free document shred event

It would be handy to capture/report the subject as well.

Sample response snippet from my area:

  "events": [
    {
      "id": XXXXXXX,
      "flags": [
        {
          "service_name": "waste",
          "event_type": "pickup",
          "subject": "Mixed recycling",
          "backgroundColor": "#007ac2",
          "voice_message": null,
          "id": XXXX,
          "short_text_message": null,
          "area_name": "XXXXXXXCounty",
          "plain_text_message": null,
          "name": "MixedRecycle",
          "html_message": "<p>Include clean paper, cardboard and metal, as well as plastic bottles, tubs and buckets in the mixed recycling roll cart.</p>\n\n<p>&nbsp;</p>\n\n<p>Extra recycling can be set on the side at no charge <a target=\"_blank\" href=\"http://rco.io/XXXXXX\">if properly prepared</a>. Contact your collection company to inquire about ordering an additional recycling cart.</p>\n\n<p>&nbsp;</p>\n\n<p>Appliances should be taken to a drop-off recycling center. Place glass in the red bin.</p>",
          "icon_uri_fragment": "0,122,194/XXXXXXXX_recycling",
          "is_week_long": 0,
          "borderColor": "#007AC2",
          "sort_order": 13,
          "color": "#007ac2",
          "opts": {
            "event_type": "pickup"
          },
          "icon": "XXXXXXX_recycling:rgb(0,122,194)"
        },
        {
          "icon_uri_fragment": "246,139,31/XXXXXXX_glass",
          "is_week_long": 0,
          "html_message": "<p>Separate glass bottles and jars from other recyclables and place in the red glass bin.</p>\n\n<p>&nbsp;</p>\n\n<p>Put vases, mirrors, dishware and broken glass in the garbage.</p>\n\n<p>&nbsp;</p>\n\n<p>Set motor oil contained in a 1-gal, see-through plastic container next to the glass bin.</p>",
          "zone_id": XXXXX,
          "event_id": XXXXXXX,
          "name": "GlassRecycle",
          "area_name": "XXXXXXXCounty",
          "short_text_message": null,
          "plain_text_message": null,
          "icon": "washington_glass:rgb(246,139,31)",
          "opts": {
            "event_type": "pickup"
          },
          "borderColor": "#F6871F",
          "color": "#f68b1f",
          "sort_order": 14,
          "subject": "Glass recycling",
          "event_type": "pickup",
          "service_name": "waste",
          "id": XXXX,
          "voice_message": null,
          "backgroundColor": "#f68b1f"
        },