Skip to content

README.md

Latest commit

 

History

History
105 lines (79 loc) · 3.84 KB

README.md

File metadata and controls

105 lines (79 loc) · 3.84 KB
Raw

where the plow

Real-time and historical tracking of snowplow vehicles across Newfoundland — St. John's, Mount Pearl, and Provincial.

Polls multiple AVL (Automatic Vehicle Location) APIs at configurable intervals, stores historical position data in DuckDB, serves it as GeoJSON, and visualizes it on a live map.

Production: https://plow.jackharrhy.dev

Running

Local

Requires uv:

uv run cli.py dev

This starts the app with auto-reload and sets DB_PATH=./data/plow.db. You can also run uvicorn directly:

uv run uvicorn where_the_plow.main:app --host 0.0.0.0 --port 8000

Docker

docker compose up -d

Either way, the app starts at http://localhost:8000. DuckDB data persists to ./data/plow.db.

Environment variables

Variable Default Description
DB_PATH /data/plow.db Path to DuckDB database file
LOG_LEVEL INFO Python log level
AVL_API_URL St. John's AVL endpoint Override the St. John's API URL
SOURCE_ST_JOHNS_ENABLED true Enable/disable St. John's source
SOURCE_ST_JOHNS_POLL_INTERVAL 6 St. John's poll interval (seconds)
SOURCE_MT_PEARL_ENABLED true Enable/disable Mount Pearl source
SOURCE_MT_PEARL_POLL_INTERVAL 30 Mount Pearl poll interval (seconds)
SOURCE_PROVINCIAL_ENABLED true Enable/disable Provincial source
SOURCE_PROVINCIAL_POLL_INTERVAL 30 Provincial poll interval (seconds)
MT_PEARL_API_URL Mount Pearl AVL endpoint Override Mount Pearl API URL
PROVINCIAL_API_URL Provincial AVL endpoint Override Provincial API URL

API

All geo endpoints return GeoJSON. Full OpenAPI docs at /docs.

Endpoint Description
GET /sources Available data sources and metadata
GET /vehicles Latest position for every vehicle (with mini-trails)
GET /vehicles/nearby?lat=&lng=&radius= Vehicles within radius (meters)
GET /vehicles/{id}/history?since=&until= Position history for one vehicle
GET /coverage?since=&until= Per-vehicle LineString trails with timestamps
GET /search?q= Geocode an address via Nominatim (cached proxy)
GET /stats Collection statistics
GET /health Health check
POST /track Record anonymous viewport focus event
POST /signup Email signup for notifications

Vehicle and coverage endpoints support a ?source= query parameter to filter by data source. All GET list endpoints support cursor-based pagination via limit and after query parameters. Write endpoints (/track, /signup) are rate-limited per IP.

Database schema

DuckDB with the spatial extension.

CREATE TABLE vehicles (
    vehicle_id    VARCHAR NOT NULL,
    source        VARCHAR NOT NULL DEFAULT 'st_johns',
    description   VARCHAR,
    vehicle_type  VARCHAR,
    first_seen    TIMESTAMPTZ NOT NULL,
    last_seen     TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (vehicle_id, source)
);

CREATE TABLE positions (
    id            BIGINT DEFAULT nextval('positions_seq'),
    vehicle_id    VARCHAR NOT NULL,
    source        VARCHAR NOT NULL DEFAULT 'st_johns',
    timestamp     TIMESTAMPTZ NOT NULL,
    collected_at  TIMESTAMPTZ NOT NULL,
    longitude     DOUBLE NOT NULL,
    latitude      DOUBLE NOT NULL,
    geom          GEOMETRY,
    bearing       INTEGER,
    speed         DOUBLE,
    is_driving    VARCHAR,
    PRIMARY KEY (vehicle_id, timestamp, source)
);

Deduplication is by (vehicle_id, timestamp, source) composite key -- if the API returns the same LocationDateTime for a vehicle from the same source, the row is skipped.

There are also viewports (analytics) and signups (email signups) tables -- see db.py for their full schemas.

Stack

Python 3.12, FastAPI, DuckDB (spatial), httpx, MapLibre GL JS, noUiSlider, Docker.