opentrash 0.1.0

Open-source cloud-native geospatial Python package for residential waste collection analytics.

opentrash

Open-source, cloud-native geospatial Python package for residential waste collection analytics. Turn months of vehicle telematics into per-parcel service signatures and per-day interactive route maps.

opentrash is a Python package for waste-collection agencies, civic technologists, and researchers studying urban operations. It ingests GPS telematics + parcel polygons + route polygons + facility locations, performs one disciplined spatial-join pass (the engine), and then produces two analytical products on top:

• Patterns — per-parcel service signatures (weekly1, weekly2, biweekly) derived from months or years of pings. Answers "for this parcel, who shows up regularly, on what day, at what hour?"
• RouteView — a self-contained interactive HTML map for one (route, day, vehicle). Shows the truck's trail as colored GPS dots, parcels colored served vs. missed, the patterns expectation overlaid on today's reality. Drop it on a USB stick, email it, host it static.

The architecture is "spatial joins are infrastructure; products are calculations." Everything downstream of the engine is pure aggregation on enriched pings.

Install

pip install opentrash

Optional extras for specific data sources:

pip install "opentrash[geotab]"     # Geotab GPS adapter
pip install "opentrash[postgres]"   # PostgreSQL/PostGIS GPS adapter
pip install "opentrash[dev]"        # pytest, ruff for development

Requires Python 3.11 or newer.

Quickstart

from datetime import date
from opentrash.engine.enrichment import enrich_pings
from opentrash.patterns.runner import run_patterns
from opentrash.routeview.runner import render_routeview

# 1. Enrich GPS pings with routes, parcels, facilities (one spatial-join pass).
enrich_pings(
    gps_cache_root="cache/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    routes_path="prep/routes.parquet",
    facilities_path="prep/facilities.parquet",
    out_root="enriched/",
    day="2026-01-18",
)

# 2. Detect per-parcel patterns over the past year.
run_patterns(
    enriched_root="enriched/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    out_root="patterns/",
    period="past_year",
)

# 3. Render an interactive HTML for one route + day + vehicle.
render_routeview(
    enriched_root="enriched/",
    segments_root="segments/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    routes_path="prep/routes.parquet",
    facilities_path="prep/facilities.parquet",
    out_root="routeview/",
    route_id="11722",
    day=date(2026, 1, 18),
    vehicle_id="815001",
    patterns_root="patterns/",
    patterns_window="2025-01-18_to_2026-01-18",
)

The output is a single self-contained .html file at routeview/2026-01-18/11722__815001.html. Open it in any browser.

Architecture

GPS ingest  →  cache  →  engine (the only spatial-join layer)
                            │
                            ↓ enriched pings
                            │
                ┌───────────┴───────────┐
                ↓                       ↓
        patterns (macro)          segments (timeline)
        per-parcel signatures           │
        across the window              ↓
                                  RouteView (micro)
                                  one (route, day, vehicle)
                                  as an interactive HTML

Patterns is the macro view; RouteView is the micro view. Together they form a validation loop: the long-period patterns predict who should show up; the single-day RouteView shows who actually did.

Documentation

• Docs site: https://opentrash.app/
• Course (12 lessons from notebook to package): https://airesearchcorps.org/opentrash/
• Issue tracker / discussions: TBD (the repository is currently private; this section will be updated once it's public)

How it's built

opentrash uses DuckDB for the heavy aggregations (set-based SQL, chunked + idempotent for large datasets), GeoPandas + Shapely for in-memory geometry work, PyProj for projections, and MapLibre GL JS for the rendered HTML maps. No commercial dependencies, no tile-provider lock-in.

License

Apache License 2.0 — see LICENSE and NOTICE.

You may use, modify, and redistribute opentrash for any purpose, including commercial use, provided you retain the license and copyright notices. Maximum adoption is the goal — spreading the knowledge.

Citation

If you use opentrash in academic work, please cite it via the metadata in CITATION.cff (also available as a "Cite this repository" button on GitHub once the repository is public).

Acknowledgments

Built by Mohamad Alsheikh Yassin under AI Research Corps (AIRC), a 501(c)(3) nonprofit. The original system was prototyped during my time at the City of San Diego; the open-source rewrite, documentation, and course material were produced independently at AIRC.