Get Around Hong Kong

Routes between two places in Hong Kong by MTR, bus, minibus, tram and ferry, best first: departure and arrival times, every walk and ride with stops, Octopus fares for the group, live next departures, traffic delays, and a link to open the trip on a live map. Also lists Klook things to do near the destination (affiliate ads).

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Start: a place name, address or \"lat,lon\" (e.g. \"Tsim Sha Tsui Star Ferry\", \"238 Nathan Road\", \"22.2988,114.1722\")"
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Destination, same forms as from"
    },
    "time": {
      "description": "ISO 8601 date-time, e.g. 2026-10-05T09:30:00+08:00 (Hong Kong is UTC+8). Default: now",
      "type": "string"
    },
    "arrive_by": {
      "default": false,
      "description": "true: time is when to arrive; false: when to leave",
      "type": "boolean"
    },
    "step_free": {
      "default": false,
      "description": "Wheelchair / step-free: avoids stairs, minibuses and trams",
      "type": "boolean"
    },
    "adults": {
      "default": 1,
      "description": "Aged 12–59",
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "children": {
      "default": 0,
      "description": "Aged 3–11",
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "seniors": {
      "default": 0,
      "description": "Aged 60+",
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "disabled": {
      "default": 0,
      "description": "Persons with disabilities",
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "language": {
      "default": "en",
      "description": "Language for place and line names: en, zh-HK (Traditional Chinese), zh-CN (Simplified), ja, ko",
      "type": "string",
      "enum": [
        "zh-HK",
        "zh-CN",
        "en",
        "ja",
        "ko"
      ]
    },
    "currency": {
      "description": "Also show fares in this currency (fares are charged in HKD). Default follows language",
      "type": "string",
      "enum": [
        "HKD",
        "USD",
        "JPY",
        "TWD",
        "CNY",
        "SGD",
        "KRW"
      ]
    },
    "options": {
      "default": 3,
      "description": "How many route options",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "bus": {
      "description": "A preferred bus or green minibus number, e.g. \"33\" or \"1A\": options are then only trips on it (its next departures from the nearest stop within about 10 minutes' walk, heading for the destination), or route_note says why there are none",
      "type": "string",
      "maxLength": 6
    }
  },
  "required": [
    "from",
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "from": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        },
        "kind": {
          "description": "mtr, bus, ferry, restaurant, hotel, attraction, address…",
          "type": "string"
        },
        "area": {
          "description": "District",
          "type": "string"
        },
        "metres": {
          "description": "Distance from near, when given",
          "type": "number"
        },
        "note": {
          "description": "Set when the match is loose: check it's the place meant",
          "type": "string"
        },
        "also": {
          "description": "Other candidates when the match is loose",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "name",
        "lat",
        "lon"
      ],
      "additionalProperties": {}
    },
    "to": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        },
        "kind": {
          "description": "mtr, bus, ferry, restaurant, hotel, attraction, address…",
          "type": "string"
        },
        "area": {
          "description": "District",
          "type": "string"
        },
        "metres": {
          "description": "Distance from near, when given",
          "type": "number"
        },
        "note": {
          "description": "Set when the match is loose: check it's the place meant",
          "type": "string"
        },
        "also": {
          "description": "Other candidates when the match is loose",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "name",
        "lat",
        "lon"
      ],
      "additionalProperties": {}
    },
    "leave_at": {
      "description": "ISO 8601",
      "type": "string"
    },
    "arrive_by": {
      "description": "ISO 8601",
      "type": "string"
    },
    "travellers": {
      "type": "object",
      "properties": {
        "adults": {
          "type": "number"
        },
        "children": {
          "type": "number"
        },
        "seniors": {
          "type": "number"
        },
        "pwd": {
          "type": "number"
        }
      },
      "required": [
        "adults",
        "children",
        "seniors",
        "pwd"
      ],
      "additionalProperties": false
    },
    "options": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "depart": {
            "type": "string",
            "description": "HH:MM, Hong Kong time"
          },
          "arrive": {
            "type": "string"
          },
          "minutes": {
            "type": "number"
          },
          "transfers": {
            "type": "number"
          },
          "best_for": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "fastest, cheapest, fewest changes, least walking"
          },
          "on_preferred_route": {
            "description": "With bus: whether this option rides it",
            "type": "boolean"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Live disruptions on this option: an MTR line it rides reporting a delay, a road incident near its bus or tram route"
          },
          "fare": {
            "type": "object",
            "properties": {
              "hkd": {
                "type": "number"
              },
              "note": {
                "type": "string"
              }
            },
            "required": [
              "note"
            ],
            "additionalProperties": {},
            "description": "Total for the group, Octopus; plus the requested currency if any"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "walk": {
                  "description": "A walk: \"4 min\"",
                  "type": "string"
                },
                "ride": {
                  "description": "A ride: \"Tsuen Wan Line\", \"Bus 6\", \"Star Ferry\"",
                  "type": "string"
                },
                "mode": {
                  "description": "SUBWAY, BUS, MINIBUS, TRAM, FERRY, FUNICULAR…",
                  "type": "string"
                },
                "towards": {
                  "type": "string"
                },
                "board": {
                  "description": "\"08:12 Tsim Sha Tsui\"",
                  "type": "string"
                },
                "alight": {
                  "type": "string"
                },
                "stops": {
                  "type": "number"
                },
                "to": {
                  "description": "Where a walk goes",
                  "type": "string"
                },
                "metres": {
                  "type": "number"
                },
                "leave_station_by": {
                  "description": "MTR exit to use, with step-free access where there is",
                  "type": "string"
                },
                "enter_station_by": {
                  "type": "string"
                },
                "next_departures_min": {
                  "description": "Minutes until the next departures from the boarding stop",
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "live": {
                  "description": "true: from the operator's live feed; false: timetable",
                  "type": "boolean"
                },
                "traffic_delay": {
                  "type": "string"
                }
              },
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "depart",
          "arrive",
          "minutes",
          "transfers",
          "best_for",
          "warnings",
          "fare",
          "steps"
        ],
        "additionalProperties": {}
      }
    },
    "message": {
      "description": "Set when no route was found",
      "type": "string"
    },
    "preferred_route": {
      "description": "The bus asked for, normalised (e.g. \"1A\")",
      "type": "string"
    },
    "route_note": {
      "description": "Why no option rides the preferred route (none near the start, not heading that way, not running now)",
      "type": "string"
    },
    "open_in_planner": {
      "type": "string",
      "description": "Link that opens this trip on the site with live times"
    },
    "things_to_do_nearby": {
      "description": "Affiliate ads (Klook): say so if shown",
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        },
        "deals": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "where": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "required": [
              "title",
              "where",
              "url"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "label",
        "deals"
      ],
      "additionalProperties": false
    },
    "source": {
      "type": "string"
    }
  },
  "required": [
    "from",
    "to",
    "travellers",
    "options",
    "open_in_planner",
    "source"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Stations, stops, landmarks, restaurants (official licence list), buildings and street addresses in Hong Kong matching the text, best first, with what each is and its coordinates. Pass near to rank a chain's branches nearest to a point.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "e.g. \"Ocean Park\", \"McDonald's\", \"彌敦道238號\""
    },
    "near": {
      "description": "\"lat,lon\" to rank branches of a chain by distance from",
      "type": "string"
    },
    "language": {
      "default": "en",
      "description": "Language for place and line names: en, zh-HK (Traditional Chinese), zh-CN (Simplified), ja, ko",
      "type": "string",
      "enum": [
        "zh-HK",
        "zh-CN",
        "en",
        "ja",
        "ko"
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "places": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          },
          "kind": {
            "description": "mtr, bus, ferry, restaurant, hotel, attraction, address…",
            "type": "string"
          },
          "area": {
            "description": "District",
            "type": "string"
          },
          "metres": {
            "description": "Distance from near, when given",
            "type": "number"
          },
          "note": {
            "description": "Set when the match is loose: check it's the place meant",
            "type": "string"
          },
          "also": {
            "description": "Other candidates when the match is loose",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "lat",
          "lon"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "places"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

What's disrupted right now: MTR lines reporting a delay (MTR's next-train feed) and open road incidents such as accidents, breakdowns and lane closures (Transport Department special traffic news). Empty lists mean nothing is reported. plan_trip also flags these on the options they affect.

{
  "type": "object",
  "properties": {
    "language": {
      "default": "en",
      "description": "Language for place and line names: en, zh-HK (Traditional Chinese), zh-CN (Simplified), ja, ko",
      "type": "string",
      "enum": [
        "zh-HK",
        "zh-CN",
        "en",
        "ja",
        "ko"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "mtr_delays": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "line",
          "note"
        ],
        "additionalProperties": false
      },
      "description": "MTR lines reporting a delay now"
    },
    "road_incidents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "what": {
            "type": "string",
            "description": "e.g. Traffic Accident, Vehicle Breakdown"
          },
          "where": {
            "type": "string"
          },
          "direction": {
            "type": "string"
          },
          "announced": {
            "description": "ISO 8601, Hong Kong time",
            "type": "string"
          },
          "details": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          }
        },
        "required": [
          "what",
          "where",
          "details"
        ],
        "additionalProperties": false
      },
      "description": "Open road incidents from the Transport Department"
    },
    "checked_at": {
      "type": "string"
    },
    "source": {
      "type": "string"
    }
  },
  "required": [
    "mtr_delays",
    "road_incidents",
    "checked_at",
    "source"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}