Taravel

Taravel is a commute planner for jeepneys and tricycles in Dasmariñas, Cavite. Pick a starting point and a destination and it shows the fastest, cheapest and fewest-rides trips, plus alternatives that avoid the main route. Every trip comes with directions: where to walk, which signboard to look for, where to get on and off, the fare, and how long the wait usually is.

Version 2 replaces the original Dijkstra + genetic algorithm with a server-side multi-criteria RAPTOR planner, and rebuilds the web front-end. See ALGORITHMS.md for the reasoning and bench/RESULTS.md for old-vs-new numbers.

Ways to get there, best first. Tapping one draws it on the map.

Step-by-step directions	On a phone
Each step is coloured like its line on the map, with the signboard to look for, where to get on and off, and the fare.	The map stays on top while the options scroll underneath.

The terminals page (/dashboard/): every jeepney and tricycle terminal, with photos.

Run it with Docker

docker compose up -d --build

Open http://localhost:3000. Stop it with:

docker compose down

Run it without Docker

Requires Node.js 20 or newer.

npm install
npm start

Tests and benchmark

npm test

npm run bench

The benchmark runs the original GA code unchanged (in legacy/) beside the new planner on the same trips and scores both with the same time and fare model. The GA is slow, so each trip gets a time budget:

LEGACY_RUNS=3 LEGACY_BUDGET_MIN=10 LEGACY_CONCURRENCY=3 npm run bench

What you can do in the app

• Search for a place or a named stop, tap the map to drop a pin, or use your current location.
• Browse by barangay under Trip options, the way the old demo page worked.
• Choose a route: the options are listed best first, each as one choice showing travel time and fare, the rides in order, and a line of facts (arrival time, walking, number of rides). Tapping one draws it on the map and opens the step-by-step directions underneath. Hovering a step highlights that leg on the map.
• Read the steps: each step is coloured like its line on the map — walk blue, jeepney red, tricycle purple — and the map marks where each step starts with a walk, jeepney or tricycle pin.
• Honest numbers: fares are shown in whole pesos, times of an hour or more read as 1 hr 5 min, and a ride whose line loops far from the direct way says so ("takes the long way round: 6.8 km of riding to cover 2.0 km").
• Change the conditions: rush-hour traffic, student / senior / PWD fares (20% off), or how far you are willing to walk — the answers are recomputed.
• Save places and reuse trips: saved places and your last five trips sit one tap away.
• Copy directions: "Copy directions" puts the whole trip in plain text, ready to paste into a chat.
• See the terminal: when a ride starts at a known terminal, its photo is shown so you can recognise the spot.
• Special tricycle (pakyaw): a door-to-door option from the nearest tricycle terminal. Its fare is agreed with the driver, so the app says "Ask the driver" instead of inventing a price. Hide it under Trip options.
• Share a trip: the URL always holds the current trip, so a copied link reopens it. Adding &steps=1 opens the first trip's directions straight away.
• See the whole network: "Show all routes" draws all 23 jeepney and tricycle routes.

Pages: the planner (/), terminals and route maps (/dashboard/), and /about.html. The old demo.html now redirects into the planner with the barangay picker open.

Street data. Walks and special tricycle trips follow real streets from OpenStreetMap, stored in data/roads.json (about 44,000 streets around Dasmariñas; © OpenStreetMap contributors, ODbL). To refresh it:

node tools/build-roads.js

Checking the routes. npm run audit runs tools/audit-routes.js: it looks for gaps and spikes in the route lines, points that sit off the streets, and trips that loop, ride past the destination, or go much further than the straight distance. It plans 400 sample trips between real places, the same way the server does.

npm run audit

Known gaps in the route data

The planner is only as good as the routes it is given. The audit turns up three things worth checking on the ground:

1. The DBB-C terminal loop. All five jeepney routes leaving DBB-C start with the same 2.5 km loop whose two ends are about 0.5 km apart. The line follows real streets, but driving between those ends is only 0.7 km in either direction, so one-way streets do not explain it. Either the jeepneys really circle that block, or the recorded trace began with a lap of the terminal. Affected rides now carry a "takes the long way round" note.
2. One-way route data. The DBB-C → Baclaran line exists in one direction only, so the app can take you to Pasay but not back. This is why 3 of the 400 sampled trips have no answer.
3. Points drawn off the road. A few points on the Paliparan ↔ Robinsons and the Salawag tricycle routes sit up to about 100 m from any street. It barely changes the answers, but it looks untidy on the map.

No keys needed. Maps use Leaflet + OpenStreetMap, so the app holds no API keys and needs no accounts; there is nothing to configure before running it. OpenStreetMap's public tile server is fine for a thesis demo; a deployment with real traffic should use a tile provider.

Screenshots

The images above live in docs/screenshots/. To refresh them after a UI change, start the app and run:

node tools/screenshots.js

It drives headless Chrome over the DevTools protocol (set CHROME if your browser is installed elsewhere).

Project layout

server.js            Express server: static pages + JSON API
engine/
  config.js          speeds, waiting times, fares, walking limits, traffic profiles (calibrate these)
  graph.js           turns data/get_data.js into routes, stops and walking transfers
  mcraptor.js        the route search
  planner.js         picks fastest / cheapest / fewest rides, builds alternatives and directions
  roads.js           street routing (A*) for walks and special tricycle trips
  terminals.js       reads the dashboard terminal list (used by the server and the audit)
data/get_data.js     the route network collected by the thesis team
data/roads.json      streets around Dasmariñas from OpenStreetMap
tools/build-roads.js downloads data/roads.json
tools/audit-routes.js checks the route data and 400 sample trips for gaps, loops and detours (npm run audit)
tools/screenshots.js  retakes the README screenshots from the running app
docs/screenshots/     the images used in this README
public/              front-end (HTML, one stylesheet, one script, images)
legacy/              the original algorithm files + a harness that runs them for the benchmark
bench/               old-vs-new comparison
test/                automated tests

API

POST /api/routes

{
  "origin": { "lat": 14.3250603, "lng": 120.9453688, "name": "Barzaga Compound" },
  "destination": { "lat": 14.3165996, "lng": 120.9853831, "name": "Coco Valley" },
  "preferences": { "traffic": "peak", "maxWalkM": 1000, "discount": "regular", "special": "include" }
}

The response holds options[], each with tags (e.g. ["Fastest"]), a summary (minutes, fare, distanceKm, walkKm, rides) and legs[] (mode, routeName, signboard, from, to, distanceKm, minutes, waitMinutes, fare, path, aroundKm (set when the ride takes the long way round: the direct distance it covers), and alsoRoutes when another line serves the same hop). Fares are whole pesos.

• GET /api/places — places and named stops for the search box.
• GET /api/terminals — terminals with their photos.
• GET /api/nearest?lat=&lng= — closest covered place to a point outside the network.
• GET /api/options — traffic profiles and walking presets the UI offers.
• GET /api/network — every route as a polyline.
• GET /healthz — health check.

Credits

The original Taravel thesis project collected the route data and built the first version of the site. The route data was generated with Python and saved as JSON.