Hong Kong Green Minibus Arrival

Real-time arrival information for Hong Kong Green Mini Buses (GMB). Supports fuzzy stop name matching and multi-region route lookup.

Security Scan

The skill's code, runtime instructions, and external requests are coherent with its stated purpose of fetching GMB arrival times; nothing requests unrelated credentials or elevated privileges.

Purpose & Capability

Name/description match the code and tools: the script queries the stated Transport Dept ETA API and a static route list to implement route search and ETA lookup. Required binaries/env vars are none, which is proportionate.

Instruction Scope

SKILL.md tools map directly to python commands that run gmb_arrival.py. The instructions only fetch route/stop/ETA data and use local caching; they do not read unrelated system files or exfiltrate data to unexpected endpoints.

Install Mechanism

No install spec (no packages downloaded), which reduces risk. The skill contains an executable Python script that the agent runs directly; caches are written to a local data/ directory under the skill. This is expected but means code is executed from the workspace without additional install-time vetting.

Credentials

The skill requires no environment variables or credentials. All network calls are to the declared endpoints (data.etagmb.gov.hk and data.hkbus.app) used to obtain route/stop/ETA information.

Persistence & Privilege

Skill does not request always:true or other elevated persistence. It writes caches only under its own data/ directory and does not attempt to modify other skills or system-wide settings.

Assessment

This skill appears to do exactly what it claims: query the HK GMB ETA API and a community route list, perform fuzzy matching, and cache results in a data/ subdirectory. Things to consider before installing: - Cached files are stored under the skill's data/ directory. If other users or processes can write to that directory, an attacker could poison cached route/stop data; ensure file permissions are appropriate. - The static route mapping is fetched from a community-hosted JSON (data.hkbus.app). The README and code note this and that the static data can lag or be stale; if you require authoritative data, verify the source yourself. - The SKILL.md had a minor URL mismatch in the Implementation Notes (mentions hkbus.github.io) but the code/README use data.hkbus.app; this looks like a documentation mismatch rather than malicious behavior. - The skill prints some error details to stderr and returns error messages in JSON. If you plan to expose outputs to untrusted parties, avoid including raw error payloads that could reveal internal paths. Overall, the skill is internally consistent and does not request unnecessary access; proceed if you trust the external data sources and the environment's file permissions.

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).