Skopje Bus Tracker

Real-time bus tracking for Skopje public transport. Modular system supporting any stop and route.

Quick Start

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
• Shareable URLs with stop/route parameters

Commands

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:

# 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:

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 to set defaults:

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