HK Bus ETA

Bus ETAs in Hong Kong is now available as open data in Hong Kong, while there is no format normalization across different transport provider. This package is a js package (typescript supported) for querying normalized public traffic ETA (Estimated Time of Arrival) in Hong Kong. The ETA data structure is based on hkbus/hk-bus-crawling and a well-established open-source project is known as hkbus.app.

A Python version package is available here and the source code is available here.

Demo

Live demo is available here.

Install

npm install hk-bus-eta or yarn add hk-bus-eta

Usage

Crawling traffic database:

import { fetchEtaDb } from "hk-bus-eta";
import type { EtaDb } from "hk-bus-eta";

(async function () {
  const etaDb: EtaDb = await fetchEtaDb();
  console.log(db)
})();

Crawling ETA

import { fetchEtas } from "hk-bus-eta";
import type { Eta } from "hk-bus-eta";

(async function () {
  // etaDb is the EtaDb object fetched by fetchEtaObj
  const etas: Eta[] = await fetchEtas({
    ...etaDb.routeList["1+1+CHUK YUEN ESTATE+STAR FERRY"],
    seq: 0,
    language: "en",
  });
  console.log(etas);
})();

Data Structure

The data structure of EtaDb is as follows:

{
    holidays: string[];
    routeList: {
        [routeId: string]: {
            route: string,
            co: Company[],
            orig: {
                en: string,
                zh: string
            },
            dest: {
                en: string,
                zh: string
            },
            fares: string[] | null,
            faresHoliday: string[] | null,
            freq: {
                [type: string]: {
                    [startTime: string]: [string, string] | null
                }
            } | null,
            jt: string | null,
            seq: number,
            serviceType: string,
            stops: {
                [company: string]: string[]
            },
            bound: {
                [company: string]: "O" | "I" | "OI" | "IO"
            },
            gtfsId: string,
            nlbId: string
        }
    }
    stopList: {
        [stopId: string]: {
            location: {
                lat: number,
                lng: number,
            },
            name: {
                en: string,
                zh: string
            }
        }
    }
    stopMap: {
        [stopId: string]: Array<{
          [company: string]: string  
        }>
    }
}

The data structure of Eta is as follows:

{
  eta: string,
  remark: {
    zh: string,
    en: string
  },
  co: string
}

Contribute

Project owner chunlaw is the initiator of the whole project. Everyone is welcome to contribute.

License

GPL-3.0 license