Table of Contents generated with DocToc

• Public Transport Waiting Times
  • Features
  • Use-case
  • Getting Started
    • Prerequisites
    • Installation
    • Running the Application
    • Running with Docker
  • Getting API Access
    • STIB/MIVB API (Belgium)
    • De Lijn API (Belgium)
    • SNCB (Belgium)
    • BKK (Budapest)
    • Mobility Database
  • Figuring out stop IDs
    • Stib
    • De Lijn
  • Configuration
  • Initial Setup
  • Configuration Files
  • Known Issues and Limitations

Public Transport Waiting Times

Creates a dashboard showing waiting times for implemented public transport companies' stops, ordered by distance from a given point (map centre or user's current location).

The aim is for a modular design that allows for easy addition of new transit providers, including in other countries.

Currently supported real-time waiting times:

• Belgium: STIB, De Lijn, SNCB, Le TEC
• Hungary: BKK

Schedule based waiting times: supported in 70 countries covered by the Mobility Database.

Alongside realtime waiting times, it creates a dashboard to browse stops and routes from static GTFS data that it can dynamically download from the Mobility Database.

Features

• Real-time waiting times for buses, trams and metros
• Configurable display of multiple stops
• Auto-refresh of waiting times
• API that can be used by other applications (e.g. a Raspberry Pi display)
• Schedule Explorer: A web interface to explore GTFS schedules and plan routes (beta)

Use-case

Mainly to power smart home displays that provide transit data (e.g. next train departures, waiting times at nearby bus stops).

Reference implementation: Raspberry Pi Waiting Time Display (ridiculously sped up)

Getting Started

Prerequisites

• API keys for STIB and De Lijn (see below) - requires free registration

Installation

Docker

See DOCKER.md for how to install it directly with Docker.

Traditional way

1. Clone this repository
2. Create a virtual environment: python -m venv .venv
3. Activate the virtual environment:
   • Windows: .venv\Scripts\activate
   • Linux/Mac: source .venv/bin/activate
4. Install dependencies: pip install -r requirements.txt
5. Copy local.py.example to local.py and add your API keys to the .env file

Running the Application

You can run all components (legacy app, Schedule Explorer frontend and backend) with a single command:

python start.py

This will start:

• Waiting time dashboard http://localhost:5001 (limited to hardcoded providers)
• Schedule Explorer frontend on http://localhost:8080 (GTFS schedule explorer - allows loading the GTFS data of all providers who are in the Mobility Database and do not require specific authentication)
• Schedule Explorer backend on http://localhost:8000 (GTFS schedule explorer API)

To stop all components, press Ctrl+C.

Alternatively, you can run individual components:

• Legacy app only: python app/main.py
• Schedule Explorer backend: cd app/schedule_explorer && uvicorn backend.main:app --reload
• Schedule Explorer frontend: cd app/schedule_explorer/frontend && python -m http.server 8080

Running with Docker

1. Copy docker-compose.yaml.example to docker-compose.yaml and add your API keys to the .env file
2. Copy local.py.example to local.py and add your API keys to the .env file - change the variables as needed
3. For outside access, an example is provided using ngrok. See docker-compose.yaml.example for details. Otherwise, remove the ngrok-static service.
4. Run the application: docker compose up
5. Access the application at http://localhost:5001 or the ngrok URL

Getting API Access

STIB/MIVB API (Belgium)

1. Go to the STIB Open Data Portal
2. Create an account and log in
3. Generate your API key in your account settings
4. Add the key to your .env file as "STIB_API_KEY"

De Lijn API (Belgium)

De Lijn static GTFS and service alerts use Belgian Mobility by default. Static GTFS is downloaded from the Belgian Mobility GTFS static endpoint and normalized back to the existing De Lijn stop, route, trip, and shape ID format used by the app.

1. Visit https://api-management-opendata-production.developer.azure-api.net/
2. Create an account and subscribe to the Standard product.
3. Add the primary or secondary key to .env as MOBILITY_API_PRIMARY_KEY or MOBILITY_API_SECONDARY_KEY.
4. Keep the De Lijn Developer Portal keys for legacy fallback and vehicle positions:
   • DELIJN_API_KEY
   • DELIJN_GTFS_STATIC_API_KEY
   • DELIJN_GTFS_REALTIME_API_KEY

Vehicle positions remain on De Lijn's legacy GTFS realtime endpoint. Belgian Mobility De Lijn TripUpdates and ServiceAlerts are not a replacement for vehicle positions unless a dedicated VehiclePositions endpoint is configured later.

Optional overrides:

DELIJN_GTFS_STATIC_SOURCE=belgian_mobility
DELIJN_SERVICE_ALERTS_SOURCE=belgian_mobility
DELIJN_VEHICLE_POSITIONS_SOURCE=legacy
DELIJN_BELGIAN_MOBILITY_GTFS_STATIC_URL=https://opendata-discovery-gtfs-static.api.production.belgianmobility.io/api/gtfs/feed/delijn/static
DELIJN_BELGIAN_MOBILITY_ALERTS_URL=https://api-management-opendata-production.azure-api.net/api/gtfs/feed/delijn/rt/alert
DELIJN_BELGIAN_MOBILITY_TRIP_UPDATES_URL=https://api-management-opendata-production.azure-api.net/api/gtfs/feed/delijn/rt/trip-update

SNCB (Belgium)

SNCB/NMBS now publishes scheduled and realtime GTFS data through the Belgian Mobility Open Data Portal.

1. Visit https://api-management-opendata-production.developer.azure-api.net/
2. Create an account and subscribe to the Standard product.
3. Add the primary or secondary key to .env as MOBILITY_API_PRIMARY_KEY or MOBILITY_API_SECONDARY_KEY.
4. Optional static fallback: add MOBILITY_API_REFRESH_TOKEN so the app can fall back to Mobility Database / GTFS.be static GTFS if Belgian Mobility static GTFS is temporarily unavailable.

The old SNCB_GTFS_REALTIME_API_URL setting is deprecated. GTFS.be's tripUpdates.pb mirror is not used as a realtime fallback because it is not reliably updated.

Le TEC (Belgium)

Le TEC publishes static GTFS, GTFS-RT trip updates, and GTFS-RT service alerts through the Belgian Mobility Open Data Portal.

1. Visit https://api-management-opendata-production.developer.azure-api.net/
2. Create an account and subscribe to the Standard product.
3. Add the primary or secondary key to .env as MOBILITY_API_PRIMARY_KEY or MOBILITY_API_SECONDARY_KEY.

Use letec as the provider ID in this app. Belgian Mobility APIM still uses the feed slug tec, so the default URLs are /api/gtfs/feed/tec/static, /api/gtfs/feed/tec/rt/trip-update, and /api/gtfs/feed/tec/rt/alert.

Le TEC GTFS-RT trip updates can use Belgian Mobility-prefixed IDs such as gs:tec:*, gr:tec:*, and gt:tec:*, and may publish delay-only stop updates. The provider normalizes those IDs and joins realtime delays to static GTFS stop_times.txt schedules before returning waiting times.

Static GTFS falls back to the official HTTPS Le TEC ZIP at https://opendata.tec-wl.be/Current%20GTFS/TEC-GTFS.zip if APIM static GTFS is unavailable.

The app does not consume Le TEC NeTEx data yet; this provider is wired for GTFS static data and GTFS-RT realtime feeds.

BKK (Budapest)

1. Visit https://opendata.bkk.hu/data-sources
2. Register and get a key under the key management option
3. Add the keys to your .env file

Mobility Database

Without an API key, you are limited to a CSV mirror of the data, that is not fully up to date.

1. Go to https://mobilitydatabase.org
2. Create an account
3. Get your API refresh key
4. Add the keys to your .env file

Figuring out stop IDs

General method:

• Go to the GTFS downloader interface of the Schedule Explorer, download the GTFS data for your provider
• Switch to the Stop explorer tab, type in your stop name
• Select the stops that appear, look for the route and direction you want to monitor
• Note down the stop_id for the relevant stop

Note that the Schedule Explorer works with a wide range of providers. There is a schedule based interface that displays the upcoming arrivals at a stop on port 8000. There is also a similar interface that displays realtime waiting times on port 5001 for the 4 providers that are currently implemented.

Stib

Alternatively:

• Explore the open data portal and find the stop ID (https://opendata.stib-mivb.be/) (You can filter by the 'where' field to narrow down the search. E.g. where: pointid="1234" to get information about a specific stop.)
• Use the STIB stop finder and look for stop= in the URL
• For each line, one direction is designated as "City" and the other as "Suburb" - it is not always the same direction as you might expect.

De Lijn

Either:

• Use the De Lijn stop finder and look for the stop ID in the URL
• Explore the open data portal and find the stop ID (https://data.delijn.be/) (Sometimes it is useful to know that Brussels is under gemeenteeNummer=3)

Configuration

Initial Setup

1. Copy the example configuration files: bash cp config/local.py.example config/local.py cp .env.example .env

2. Edit config/local.py to set your:

   • Monitored stops and lines
   • Map center coordinates and zoom level
   • Other custom settings

3. Edit .env to add your API keys:

   • STIB/MIVB API key
   • De Lijn API keys (regular, GTFS static, and GTFS realtime)
   • NGROK_AUTHTOKEN (if using ngrok)
   • NGROK_DOMAIN (if using ngrok)

Configuration Files

• config/default.py: Default settings (do not edit)
• config/local.py: Your local settings (edit this)
• .env: Environment variables and API keys

Known Issues and Limitations

• The De Lijn setup is not yet fully set up for multiple monitored lines.