Laramie Trash & Recycling Schedule API Client

A Python client for accessing the City of Laramie, Wyoming's trash and recycling collection schedule via the ReCollect API.

Features

• Look up collection schedules by address
• Email notifications via Gmail
• MQTT publishing for Home Assistant
• Docker support for automated reminders
• GitHub Actions for scheduled notifications
• JSON output for integrations

Installation

git clone https://github.com/andrefecto/laramie-recollect.git
cd laramie-recollect

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

Usage

Command Line

# Run API tests
python recollect.py

# Look up collection schedule
python recollect.py "123 Main St"

# Output as JSON (for integrations)
python recollect.py "123 Main St" --json

# Send email notification
export RECOLLECT_GMAIL_USER="you@gmail.com"
export RECOLLECT_GMAIL_PASS="your-app-password"
python recollect.py "123 Main St" --notify

As a Library

from recollect import get_schedule_for_address, get_json_output

place, schedule = get_schedule_for_address("123 Main St", quiet=True)
data = get_json_output(place, schedule)

print(data["next_pickup"])  # {'date': '2026-01-20', 'types': ['Trash']}

Email Notifications

Send yourself reminders using Gmail SMTP:

1. Enable 2-Step Verification on your Google Account
2. Generate an App Password: Google Account → Security → App Passwords
3. Set environment variables:

export RECOLLECT_GMAIL_USER="you@gmail.com"
export RECOLLECT_GMAIL_PASS="your-app-password"
export RECOLLECT_NOTIFY_EMAIL="you@gmail.com"  # Optional, defaults to GMAIL_USER

Docker

Quick Run

docker build -t recollect .

docker run -e RECOLLECT_ADDRESS="123 Main St" \
           -e RECOLLECT_GMAIL_USER="you@gmail.com" \
           -e RECOLLECT_GMAIL_PASS="app-password" \
           recollect

Docker Compose

# Create .env file with your settings
cp .env.example .env

# Send notification
docker compose --profile notify up

# Publish to MQTT
docker compose --profile mqtt up

GitHub Actions

Automated daily reminders via GitHub Actions:

1. Fork this repository
2. Add secrets in Settings → Secrets → Actions:
   • RECOLLECT_ADDRESS - Your street address
   • RECOLLECT_GMAIL_USER - Your Gmail address
   • RECOLLECT_GMAIL_PASS - Gmail app password
   • RECOLLECT_NOTIFY_EMAIL - Where to send notifications
3. The workflow runs daily at 6 PM Mountain Time

Home Assistant

See homeassistant/README.md for integration options:

• Command Line Sensor
• MQTT with auto-discovery
• RESTful Sensor
• Example automations and cards

Environment Variables

Variable	Description
RECOLLECT_ADDRESS	Street address to look up
RECOLLECT_GMAIL_USER	Gmail address for sending notifications
RECOLLECT_GMAIL_PASS	Gmail app password
RECOLLECT_NOTIFY_EMAIL	Email to send notifications to
RECOLLECT_NOTIFY_DAYS	Days before pickup to notify (e.g., "3,1")
RECOLLECT_FORCE_NOTIFY	Set "true" to always send notification
RECOLLECT_MQTT_HOST	MQTT broker hostname
RECOLLECT_MQTT_PORT	MQTT broker port (default: 1883)
RECOLLECT_MQTT_USER	MQTT username
RECOLLECT_MQTT_PASS	MQTT password
RECOLLECT_MQTT_TOPIC	MQTT topic prefix

Notification timing examples:

• RECOLLECT_NOTIFY_DAYS=1 - Notify 1 day before pickup (default)
• RECOLLECT_NOTIFY_DAYS=3,1 - Notify 3 days before AND 1 day before
• RECOLLECT_NOTIFY_DAYS=7,3,1 - Weekly reminder, 3-day, and day-before

API Reference

This client uses the ReCollect API:

Endpoint	Description
GET /api/areas/{area}/services/{id}.json	Service information
GET /api/.../address-suggest?q={query}	Address search
GET /api/places/{place_id}	Place details
GET /api/places/{id}/services/{id}/events	Collection schedule

Notes

• Trash is collected weekly
• Recycling is collected every other week
• Collection schedules may change during holidays
• This is an unofficial client, not affiliated with the City of Laramie

Contributing

Contributions welcome! Ideas:

• Support for other cities using ReCollect
• ICS calendar file generation
• SMS notifications via Twilio
• Home Assistant custom component

Support

If you find this useful, consider buying me a coffee!

License

MIT License - see LICENSE for details.