218 lines
6.3 KiB
Markdown
218 lines
6.3 KiB
Markdown
# Skopje Bus Tracker
|
||
|
||
Real-time bus tracking for Skopje public transport. Modular system supporting any stop and route.
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
npm install
|
||
npm run setup-gtfs # Download latest GTFS data
|
||
npm run web
|
||
```
|
||
|
||
Open **http://localhost:3000**
|
||
|
||
Visit **http://localhost:3000/analytics.html** for historical data and performance analytics.
|
||
|
||
## TimescaleDB Setup
|
||
|
||
The application uses TimescaleDB for storing time-series data (vehicle positions, arrivals, delays).
|
||
|
||
### Start the database:
|
||
|
||
```bash
|
||
cd infrastructure
|
||
docker compose up -d
|
||
```
|
||
|
||
### Configure environment:
|
||
|
||
Create a `.env` file (or use the defaults):
|
||
|
||
```bash
|
||
POSTGRES_HOST=localhost
|
||
POSTGRES_PORT=5432
|
||
POSTGRES_DB=iot_data
|
||
POSTGRES_USER=postgres
|
||
POSTGRES_PASSWORD=example
|
||
```
|
||
|
||
The database will automatically:
|
||
- Create hypertables for efficient time-series queries
|
||
- Set up compression and retention policies (90 days)
|
||
- Build continuous aggregates for hourly metrics
|
||
- Index data for fast queries
|
||
|
||
### Analytics Features:
|
||
|
||
- **Vehicle Position History**: Track individual buses over time
|
||
- **Delay Analysis**: On-time performance, average delays, patterns
|
||
- **Hourly Patterns**: See when buses are typically late/early
|
||
- **Route Statistics**: Reliability scores, service quality metrics
|
||
- **Stop Performance**: Compare delays across different stops
|
||
|
||
### Background Tracker:
|
||
|
||
For continuous data collection without keeping the web interface open:
|
||
|
||
```bash
|
||
npm run track
|
||
```
|
||
|
||
This automatically tracks these popular routes every 30 seconds:
|
||
- Routes: 2, 4, 5, 7, 15, 21, 22, 24
|
||
- Private routes: 12П, 19П, 22П, 45П, 52П, 54П, 61П, 9П
|
||
|
||
Data is stored in TimescaleDB for historical analysis. The tracker runs indefinitely until stopped with Ctrl+C.
|
||
|
||
## Features
|
||
|
||
- **Fully Modular Web Interface**: Select any stop and route via UI controls or URL parameters
|
||
- **Dynamic Tracking**: Change stops/routes without restarting the server
|
||
- Interactive map with live vehicle positions
|
||
- Real-time arrivals with delays
|
||
- **Time-Series Data Storage**: Historical tracking with TimescaleDB
|
||
- **Analytics Dashboard**: Delay statistics, hourly patterns, performance metrics
|
||
- 5-second auto-refresh (web), 10-second (terminal)
|
||
- CLI arguments for terminal tracker
|
||
- Configurable defaults via [config.ts](config.ts)
|
||
- Shareable URLs with stop/route parameters
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
npm run setup-gtfs # Download GTFS data
|
||
npm run find -- --stop "american" # Find stop IDs by name
|
||
npm run find -- --route "7" # Find route IDs by number/name
|
||
npm run web # Web interface at http://localhost:3000
|
||
npm run tracker # Terminal interface (default)
|
||
npm run tracker -- --stop 1571 --route 125 # Custom stop/route
|
||
npm run track # Background tracker for popular routes (30s intervals)
|
||
npm start # Same as web
|
||
```
|
||
|
||
### Finding Stop and Route IDs
|
||
|
||
Not sure which Stop ID or Route ID to use? Use the find command:
|
||
|
||
```bash
|
||
# Find stops by name (case-insensitive)
|
||
npm run find -- --stop "american"
|
||
npm run find -- --stop "центар"
|
||
|
||
# Find routes by number or name
|
||
npm run find -- --route "7"
|
||
npm run find -- --route "линија"
|
||
```
|
||
|
||
### Web Interface Usage
|
||
|
||
1. **Default tracking**: Open `http://localhost:3000` (loads default stop/route, can be changed in UI)
|
||
2. **Direct URL**: `http://localhost:3000?stopId=1571&routeId=125` (bookmarkable)
|
||
3. **Change tracking**: Use the controls at the top to enter different Stop ID and Route ID
|
||
4. **Share**: Copy URL after selecting a stop/route to share with others
|
||
|
||
### CLI Arguments
|
||
|
||
Terminal tracker supports custom stop and route:
|
||
|
||
```bash
|
||
npm run tracker -- --stop <stopId> --route <routeId>
|
||
npm run tracker -- --help
|
||
```
|
||
|
||
### API Endpoints
|
||
|
||
**This Application's API:**
|
||
- Complete docs: **[API-DOCUMENTATION.md](API-DOCUMENTATION.md)**
|
||
- Interactive docs: http://localhost:3000/api-docs.html (when server is running)
|
||
- OpenAPI spec: **[openapi.yaml](openapi.yaml)**
|
||
|
||
**Upstream ModeShift GTFS API:**
|
||
- Documentation: **[UPSTREAM-API-DOCUMENTATION.md](UPSTREAM-API-DOCUMENTATION.md)**
|
||
- Provider: ModeShift (Skopje public transport data)
|
||
|
||
#### Quick Reference
|
||
|
||
Query parameters for custom tracking:
|
||
|
||
```
|
||
GET /api/config?stopId=1571&routeId=125
|
||
GET /api/arrivals?stopId=1571&routeId=125
|
||
GET /api/vehicles?routeId=125
|
||
GET /api/stops # All stops
|
||
GET /api/routes # All routes
|
||
|
||
# Historical Data APIs
|
||
GET /api/stats/db # Database statistics
|
||
GET /api/history/vehicle/:vehicleId?hours=24
|
||
GET /api/history/route/:routeId/vehicles?hours=24
|
||
GET /api/history/stop/:stopId/arrivals?routeId=125&hours=24
|
||
GET /api/stats/route/:routeId/delays?hours=24
|
||
GET /api/stats/stop/:stopId/delays?hours=24
|
||
GET /api/stats/route/:routeId/hourly?days=7
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Edit [config.ts](config.ts) to set defaults:
|
||
|
||
```typescript
|
||
export const config: AppConfig = {
|
||
defaultStop: {
|
||
stopId: '1571',
|
||
name: 'АМЕРИКАН КОЛЕЏ-КОН ЦЕНТАР',
|
||
lat: 41.98057556152344,
|
||
lon: 21.457794189453125,
|
||
},
|
||
defaultRoute: {
|
||
routeId: '125',
|
||
shortName: '7',
|
||
name: 'ЛИНИЈА 7',
|
||
},
|
||
server: {
|
||
port: 3000,
|
||
},
|
||
tracking: {
|
||
refreshInterval: {
|
||
web: 5000, // 5 seconds
|
||
terminal: 10000, // 10 seconds
|
||
},
|
||
minutesAhead: 90,
|
||
}, + analytics)
|
||
├── bus-tracker-json.ts # Terminal tracker (CLI args)
|
||
├── lib/
|
||
│ ├── gtfs.ts # GTFS loader
|
||
│ └── database.ts # TimescaleDB time-series storage
|
||
├── public/
|
||
│ ├── index.html # Live tracker UI
|
||
│ └── analytics.html # Analytics dashboard
|
||
├── infrastructure/
|
||
│ └── compose.yml # TimescaleDB Docker setup
|
||
└── gtfs/ ure
|
||
|
||
```
|
||
bus/
|
||
├── config.ts # Configuration (stops, routes, timing)
|
||
├── setup-gtfs.ts # GTFS data downloader
|
||
├── find-stops-routes.ts # Helper to find Stop/Route IDs
|
||
├── server.ts # Web server (modular API)
|
||
├── bus-tracker-json.ts # Terminal tracker (CLI args)
|
||
├── lib/gtfs.ts # GTFS loader
|
||
├── public/index.html # Frontend (modular UI)
|
||
└─**TimescaleDB (PostgreSQL)** for time-series data
|
||
- Leaflet.js + OpenStreetMap
|
||
- Chart.js for analytics visualizations
|
||
- GTFS + GTFS-RT Protocol Buffers
|
||
- Docker Compose for database
|
||
|
||
## Stack
|
||
|
||
- Node.js + Express + TypeScript
|
||
- Leaflet.js + OpenStreetMap
|
||
- GTFS + GTFS-RT Protocol Buffers
|
||
|
||
## License
|
||
|
||
MIT
|