HK Route — Hong Kong Transit Routing with Real-Time ETAs

What this skill does

Finds the best public transport route in Hong Kong by combining Google Maps directions with real-time bus ETAs. Routes are ranked by effective total time (real-time wait + travel duration), not just schedule data.

Required environment

GOOGLE_MAPS_API_KEY

node

External endpoints

This skill makes network requests to:

maps.googleapis.com

GOOGLE_MAPS_API_KEY

No other network calls are made. The ETA database is cached locally at

~/.cache/hk-route/etaDb.json

Source code

The bundled

scripts/hk-route.cjs

esbuild src/index.ts --bundle --platform=node --format=cjs

How to invoke

node /path/to/skill/scripts/hk-route.cjs \
  --origin "<origin>" \
  --destination "<destination>"

The

scripts/hk-route.cjs

bundle is self-contained — no

npm install

needed. Just

node

>= 18.

Optional flags

• --departure-time "<ISO 8601 datetime>"

  — plan a future trip (e.g.,

  --departure-time "2026-03-26T08:00:00+08:00"

  )

Input formats

• Coordinates:

  "22.2822,114.1875"

  (lat,lng — no space after comma)
• Place name:

  "Causeway Bay"

  ,

  "Hong Kong Airport"

  ,

  "Stanley Market"

• Both origin and destination accept either format.

Conversational flows

One-shot (user provides both locations)

User: "How do I get from Causeway Bay to Stanley?" → Run the CLI with

--origin "Causeway Bay" --destination "Stanley"

Multi-turn (e.g., WhatsApp via OpenClaw)

1. User sends

   /hkroute

2. Ask: "Where are you now? Send a location pin or type your location."
3. User sends a coordinate pin (e.g.,

   22.2822,114.1875

   ) or text (e.g., "Tin Hau MTR")
4. Ask: "Where do you want to go?"
5. User sends destination as text or coordinates.
6. Run the CLI, format the output.

If the user provides invalid input at any step, ask them to try again with a valid location.

Implicit activation

Activate this skill when the user asks about getting somewhere in Hong Kong by public transport, even without using

/hkroute

Output format

The CLI outputs JSON to stdout. Format it for the user as follows:

WhatsApp / messaging format template

🚌 **Routes from {origin} to {destination}**

⭐ **Route 1 (Recommended)** — {effective_total_min} min
{for each leg:}
  🚶 Walk {duration_seconds/60} min — {instructions}
  🚌 Bus {route_number} from {departure_stop} — **Next bus: {etas[0] formatted as relative time}** (then {etas[1]})
     {num_stops} stops → {arrival_stop}
  🚇 MTR {route_number} from {departure_stop}
     {num_stops} stops → {arrival_stop}
  ⛴️ Ferry ...
  🚊 Light Rail / Tram ...

📍 Route 2 — {effective_total_min} min
{same leg format}

📍 Route 3 — {effective_total_min} min
{same leg format}

Formatting rules

• Recommended route: Mark with ⭐ and "(Recommended)"
• Actionable leg: The leg with

  actionable: true

  is the one that determines when the user needs to leave. Call it out prominently: "Next bus in X min — leave now!" or "Next bus in X min — you have time."
• ETAs: Format as relative time ("in 3 min", "in 12 min"). Show up to 2 ETAs per bus leg.
• Walking legs: Always show with duration. Use 🚶 emoji.
• Transport emojis: 🚌 bus, 🚇 MTR/subway, ⛴️ ferry, 🚊 light rail/tram, 🚶 walk
• Bold: Use bold for ETAs, route numbers, and the recommended route label.
• Unavailable ETAs: If

  eta_source

  is

  "unavailable"

  , show "ETA unavailable (scheduled: {departure_time})" instead of a real-time ETA.
• Schedule-only: If

  eta_source

  is

  "schedule"

  , show the scheduled departure time without a real-time label.

Error handling

If the CLI returns

error: true

• NO_TRANSIT_ROUTES

  : Tell the user no transit routes were found. Suggest trying a different departure time or considering a taxi.

• GOOGLE_API_ERROR

  : Tell the user there was an issue fetching routes. Suggest trying again.

• INVALID_INPUT

  : Tell the user what was wrong with their input.