hkbus / hk-bus-eta

Query the ETA (Estimated Time of Arrival) of HK Bus

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 { fetchEtaObj } from "hk-bus-eta";
import type { BusDb } from "hk-bus-eta";

fetchEtaDb().then((db: BusDb) => {
  console.log(db)
})

Crawling ETA

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

// busDb is the BusDb object fetched by fetchEtaObj

fetchEtas({
  ...busDb.routeList["1+1+CHUK YUEN ESTATE+STAR FERRY"],
  seq: 0,
  language: "en",
}).then(etas => {
  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