Skip to content

A tiny Python tool that infers real inter-stop bus travel times from KMB (Hong Kong) live ETAs, logs them to CSV, and visualizes variability over time.

Notifications You must be signed in to change notification settings

yuzhenfeng2002/KMB-InterStop-TravelTime-Logger-Python

Repository files navigation

KMB (Hong Kong) Inter-Stop Travel Time Logger

This code infers actual travel times between two KMB (Hong Kong) bus stops by watching live ETAs, detecting when the front-most bus “hands off” to the next one, and pairing arrivals at Stop A and Stop B to compute A→B trip durations. Results are appended to CSV so you can analyze rush-hour patterns, reliability, and variability (see sample chart in output.png).

Sample chart

Features

  • Automatic route discovery: Finds every (route, direction, service_type) that serves STOP_A then STOP_B in order, using KMB’s open-data endpoints, and caches the discovery to route_configs_*.csv.
  • ETA front-runner tracking: Tracks the front-most bus (eta_seq == 1) at each stop and emits an arrival timestamp whenever that identity switches to the next bus (a “handoff”).
  • Robust pairing: Pairs A-arrivals to later B-arrivals per (route, dir, service_type) to compute travel seconds/minutes, writing each observation to a long-lived CSV.
  • Graceful, durable logging: Files are opened once and flushed as data arrives; press Ctrl+C to stop safely.

How it works (high level)

  1. Discover configs that include both stops in order (seqA < seqB) for each route/direction/service type. These are saved/loaded via route_configs_{STOP_A}_{STOP_B}.csv.
  2. Create a FrontWatcher for Stop A and Stop B for each config. When the top ETA identity changes beyond a tolerance, we infer the previous bus has arrived and log the timestamp.
  3. FIFO pair: For each config, match the earliest unpaired A-arrival with the next B-arrival to compute travel_seconds / travel_minutes, then append to travel_times_*.csv.

Requirements

  • Python 3.9+ and the requests library.

Install:

python -m pip install requests

Quick start

  1. Edit stops: In main.py, set STOP_A and STOP_B to your two KMB stop IDs and names (lat/long are optional metadata).
  2. Run the logger:
python main.py
  1. Let it run through the periods you care about (e.g., weekday mornings). Stop with Ctrl+C.
  2. Explore the generated CSVs or open the included notebook/script to chart distributions (see output.png for an example visualization).

Configuration & tuning

  • POLL_SECONDS: how often to poll KMB ETAs. Default 20s (KMB updates roughly once per minute).
  • HANDOFF_TOL_SECS: if the top ETA’s timestamp jumps by more than this when the front bus changes, treat it as a real swap/arrival. Default 60s.

KMB data endpoints

The script uses the official KMB open-data APIs for routes, route stops, and stop ETAs (configured at the top of the file).

Output files

  • Route config cache: route_configs_{STOP_A}_{STOP_B}.csv — all (route, dir, service_type, seqA, seqB) serving A→B.

  • Arrivals (per stop): arrivals_{stop_id}.csv with columns:

    logged_at_utc, route, dir, service_type, stop_id, stop_name, seq, arrived_at_utc
    
  • Travel times (A→B): travel_times_{STOP_A}_{STOP_B}.csv with columns:

    logged_at_utc, route, dir, service_type,
    from_stop_id, from_stop_name, to_stop_id, to_stop_name,
    seq_from, seq_to, arrive_from_utc, arrive_to_utc,
    travel_seconds, travel_minutes
    

About

A tiny Python tool that infers real inter-stop bus travel times from KMB (Hong Kong) live ETAs, logs them to CSV, and visualizes variability over time.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published