act-nxtbus-api

npm package

TypeScript wrapper for Transport Canberra's NXTBUS API.

This package allows translation to a more modern JSON format compared to the XML garbage which NXTBUS spits out.

Info here, and here.

API Key (required)

Register for an API key here

Usage

1. Install with npm:

   npm i nxtbus

2. Use in a Node JS/TS project:

   import { NxtbusAPI } from 'nxtbus';
   
   const nxtbus = new NxtbusAPI(process.env.NXTBUS_API_KEY)
   const route45BusLocations = await nxtbus.getBusLocations(45)
   const locationJson = await route45BusLocations.json()
   
   console.log(JSON.stringify(locationJson, null, 2))

   Produces:

   {
       "timestamp": "2023-01-03T16:19:03+11:00",
       "status": true,
       "vehicles": [
           {
           "recordedAt": "2023-01-03T16:18:51.549+11:00",
           "validUntil": "2023-01-03T16:29:03+11:00",
           "route": "VM_ACT_0045",
           "progress": {
               "distance": 294,
               "percentage": 54
           },
           "bus": {
               "direction": "B",
               "datedVehicleJourney": "3043-00004-1",
               "pattern": "115",
   ...

The API

Our nxtbus module provides integration with ACT Government's bus stop and vehicle monitoring API.

Each API function returns a form of ServiceResponse, which can display both XML and JSON outputs, as well as an interactive cheerio interface within Node.

Note: see the official API reference PDF linked above for information on specific fields.

Creating a client instance

Once you have an API key, you can create an instance of nxtbus like so:

1. First, import the NxtbusAPI class:

   import { NxtbusAPI } from 'nxtbus'

2. Then, create an instance of the object using your key:

   const nxtbus = new NxtbusAPI(process.env.NXTBUS_API_KEY)

Now you can pull data from the API.

Getting bus locations from a route

To track all buses on a specific route, use nxtbus.getBusLocations.

Let's get the bus locations on route 45, and return it in both XML and JSON formats.

1. First, await the getBusLocations function:

   const locations = await nxtbus.getBusLocations(45)

2. To display the XML, you can simply log it to the console:

   console.log(locations.xml)

3. JSON is a 2 line process, as the nxtbus package does some work in the background to add the locations of bus stops.

   const locationsJson = await locations.json()
   console.log(JSON.stringify(locationsJson, null, 2))

Getting bus locations relative to a bus stop

To track incoming buses for a specific stop, first you need the bus stop's ID. That can be obtained from the CSV located here (The nxtbus package pulls this file in the background for up-to-date bus stop information).

The same XML/JSON rules apply here. XML will be skipped; we'll just print the JSON output.

This will uses the bus stop 4455 - Erldunda Cct opp Hawker PS

1. await the getIncomingBuses function:

   const busesToStop = await nxtbus.getIncomingBuses(4455)

2. await the JSON return:

   const stopJson = await busesToStop.json()

3. Log the output to the console:

   console.log(JSON.stringify(stopJson, null, 2))

To do

Add productionTimetable and estimatedTimetable endpoints.