Implementation Notes

API Endpoints (Base URL: https://data.etagmb.gov.hk)

• GET /route - List all routes grouped by region (HKI, KLN, NT)
• GET /route/{region}/{route} - Get route details including directions (route_seq) and route_id
• GET /stop-route/{stop_id} - Get stop names (name_en, name_tc) and the routes serving that stop
• GET /eta/stop/{stop_id} - Get real-time ETA for all routes at that stop

Additionally, static route data is sourced from:

• https://hkbus.github.io/hk-bus-crawling/routeFareList.min.json - Contains mapping from route identifiers to stop ID sequences for GMB (and other operators).

Script: gmb_arrival.py

Key functions:

• searchRoutes(route): Queries /route, finds which regions contain this route number. If none, suggests similar route numbers.
• get_gmb_arrival(route, direction, stop_name, region):
  1. Fetch /route/{region}/{route} to obtain route_id and the direction details (origin/destination names).
  2. Construct composite route key using the origin/destination English names and load from routeFareList.json to get the ordered list of stop IDs for that direction.
  3. For each stop ID along the route, fetch /stop-route/{stop_id} to retrieve stop names (cached).
  4. Match the user-provided stop_name (case-insensitive) exactly; if not found, perform fuzzy matching and return suggestions.
  5. Once stop ID is identified, call /eta/stop/{stop_id}.
  6. Filter ETA entries for the desired route_id and route_seq (direction), extract up to 3 next arrival timestamps, format as "HH:MM HKT".
  7. Return JSON: { "stopId": "...", "stopName": "...", "arrivals": [ "17:35 HKT", ... ] }.

Caching Strategy

• routes_all.json: All route list (1 hour)
• route_details.json: Route details per region/route (5 minutes)
• routeFareList.json: Static route-to-stop mapping (1 day)
• stop_names.json: Stop ID to names mapping (1 week)
• ETA responses: 30 seconds

Cache files stored in data/ subdirectory.

Error Handling

• Network errors and API failures are caught and reported in JSON with an error field.
• If route not found: returns found: false with suggestions array.
• If stop name not found: returns error with suggestions mapping suggestion → stop ID.
• If no active ETA: returns empty arrivals array with an informative message.

Usage Example (Command Line)

# Search route
python3 gmb_arrival.py searchRoutes 1
# => {"route":"1","found":true,"regions":["HKI","KLN","NT"]}

# Get arrival for route 1 direction 1 (The Peak → Central) at "Hong Kong Station Minibus Terminus" in HKI
python3 gmb_arrival.py getGMBArrival 1 1 "Hong Kong Station Minibus Terminus" HKI
# => {"stopId":"20014492","stopName":"Hong Kong Station Minibus Terminus","arrivals":["14:38 HKT","14:45 HKT","14:52 HKT"]}

Notes

• Direction sequence: For each GMB route, the API defines route_seq 1 and 2. Use searchRoutes then inspect route details to determine which sequence corresponds to your desired direction, or use getGMBArrival directly if you know the direction number.
• Stop names are matched case-insensitively. Chinese or English names both work.
• The static routeFareList may lag behind official data by up to one day but is generally reliable.
• Rate limits: The script caches aggressively to minimize API calls; still, avoid excessive polling (ETA updates every minute).