131 lines
3.3 KiB
Markdown
131 lines
3.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**
|
||
|
||
## 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
|
||
- 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 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
|
||
|
||
Query parameters for custom tracking:
|
||
|
||
```
|
||
GET /api/config?stopId=1571&routeId=125
|
||
GET /api/arrivals?stopId=1571&routeId=125
|
||
GET /api/vehicles?routeId=125
|
||
```
|
||
|
||
## 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,
|
||
},
|
||
};
|
||
```
|
||
|
||
## Structure
|
||
|
||
```
|
||
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)
|
||
└── gtfs/ # Static data (auto-downloaded)
|
||
```
|
||
|
||
## Stack
|
||
|
||
- Node.js + Express + TypeScript
|
||
- Leaflet.js + OpenStreetMap
|
||
- GTFS + GTFS-RT Protocol Buffers
|
||
|
||
## License
|
||
|
||
MIT
|