Pluto-3/njia

East African freight routing API — OSM-based road network processed into pgRouting topology # njia East African freight routing API. Given an origin, destination, truck class, and cargo type, it returns a route optimized for the realities of moving freight across Tanzania, Kenya, and Uganda — not just the shortest path. ## What it does - Builds a road network from raw OSM data (Tanzania/Kenya/Uganda extracts), scored for road quality rather than treating every road as equal. - Routes are annotated with: - **Checkpoints** (border crossings, weighbridges) and expected wait times - **Risk flags** — flood zones, poor road segments, seasonal closures — with severity levels - **Seasonal risk** for the requested departure date - **Fuel and transit-time estimates** - Responses are bilingual (English/Swahili) for waypoint and risk descriptions. - Tiered API key auth with daily request limits (free/paid). ## Example ``` POST /v1/route Authorization: Bearer { "origin": "Dar es Salaam Port, Tanzania", "destination": "Kigali, Rwanda", "truck_class": "semi", "cargo_type": "dry_goods", "departure_date": "2026-09-01", "alternatives": 1, "language": "en" } ``` Returns a primary route plus alternatives, each with waypoints (road-quality-scored), distance, checkpoints, risk flags, seasonal risk level, and fuel/time estimates. ## Stack FastAPI (async) + PostGIS/pgRouting for the road network, SQLAlchemy/asyncpg, Docker Compose for the DB. See `Makefile` for the full data pipeline (download → merge → filter → load → classify → topology → seed). ## Status Core routing, checkpoints, risk annotation, and seasonal logic are built and verified against the live network. Path-finding currently runs on pgRouting, which works correctly but doesn't yet meet the project's own latency target at this scale — an OSRM-based migration is designed (see `njia-notes/osrm_migration_plan.md`) and in progress. ## Running locally ```bash make db-up # start PostGIS+pgRouting make pipeline # build the road network (download → ... → seed) uvicorn app.main:app --reload ``` `GET …