hk-bus-eta

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

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