opentrash

A geospatial Python package for residential waste collection analytics.

opentrash turns vehicle GPS telematics, parcel polygons, route polygons, and facility locations into operational intelligence: per-parcel service signatures that span months or years, and self-contained interactive maps of a single route on a single day. It runs on a laptop, scales to fleet-wide datasets via DuckDB, and produces outputs that anyone with a web browser can open.

The package is designed for waste-collection agencies, civic technologists, operations researchers, and anyone building tools on top of vehicle-fleet data. It is open source under the Apache License 2.0, has no commercial dependencies, and is not locked to any vendor's data format.

Install · Quickstart · Features · Roadmap

---

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 and ruff for development

Requires Python 3.11 or newer. Tested on Linux and macOS; Windows support is available but less exercised — please report issues.

---

Quickstart

The three core entry points form a pipeline: enrich GPS, detect patterns, render a route view.

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, and facilities.
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 on one day.
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",
)

The output is a single self-contained .html file at routeview/2026-01-18/11722__815001.html. No server, no tile-provider key, no signup — open it in any browser.

For a longer walkthrough with sample data, see Getting started.

---

Features

The routing engine

A single, disciplined spatial-join layer (opentrash.engine) joins every GPS ping against every operational GIS layer — routes, parcels, facilities — exactly once. Every downstream product reads enriched pings and applies its own arithmetic. The principle is spatial joins are infrastructure; products are calculations.

Patterns

Per-parcel service-signature detection (opentrash.patterns) processes months or years of GPS history to surface the typical service for each parcel: weekly, biweekly, day-of-week, hour-of-day, and which vehicle. Outputs are partitioned parquet files, idempotent, and skip-if-fresh.

RouteView

Single-route, single-day, single-vehicle interactive HTML maps (opentrash.routeview). The truck's GPS trail renders as colored dots (granularity preserved, not collapsed into polylines), parcels color by served / missed / unknown, patterns expectations appear in parcel popups, and per-load tonnage is matched by vehicle and time window.

GPS adapters

Pluggable adapters (opentrash.adapters.gps) for ingesting GPS data from multiple sources. Ships with adapters for the Geotab telematics API and PostgreSQL/PostGIS. Each adapter implements a small read-only protocol, so adding a new source is straightforward.

Tonnage ingest

A hash-based, idempotent pipeline (opentrash.tonnage) for landfill weight records, with cleaners for the RAD and ARTS source formats. Year-partitioned on disk, designed for incremental updates.

Static layer preparation

One-time data preparation tools (opentrash.prep) for parcels, routes, facilities, and service-site polygons. Geometries are stored as WKB-backed parquet for fast load and spatial-join performance.

---

How it's built

opentrash uses DuckDB for set-based aggregations (chunked and idempotent for large datasets), GeoPandas + Shapely for in-memory geometry, PyProj for projections, and MapLibre GL JS for rendered HTML maps. No commercial dependencies; no tile-provider lock-in. The working CRS is EPSG:2230 (CA State Plane Zone 6, US feet) by default; the web CRS is EPSG:4326.

See Architecture for the full structural overview.

---

License and citation

opentrash is licensed under the Apache License 2.0. You may use, modify, and redistribute it for any purpose, including commercial use, provided you retain the license and copyright notices.

For academic work, please cite the package using the metadata in CITATION.cff.