# Hk Gmb Arrival

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

- Skill: `stevenho1394/hk-gmb-arrival` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add stevenho1394/hk-gmb-arrival`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stevenho1394/hk-gmb-arrival/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: StevenHo1394 (https://skillmd.com/u/stevenho1394)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/stevenho1394/hk-gmb-arrival

---

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

```bash
# 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).