bustime

An abstraction of the Clever Devices BusTime developer API

View the Project on GitHub agarzola/bustime

bustime

An abstraction of the Clever Devices BusTime API, used by transit authorities across the U.S. bustime takes parameter values as a JavaScript object and returns the API’s response also as an object. You need not worry about generating query parameters or parsing XML responses! Yay!

Now with utility methods to help you mine data from your API!

::::::::::::::: Probably not production ready! (But it’s close!) :::::::::::::::

Contents

Installation

$ npm install bustime

(You probably want to --save it as a dependency, but I ain’t the boss of you.)

Usage

Before you require bustime, you should create an object with at least your API key and the host. This object is then passed as an argument of require, like so:

var bustime = require('bustime');

var apiObj = {
    key: 'your_api_key',       // required
    host: 'your_api_host.com', // required
    localestring: 'lang',      // optional, default is whatever the BusTime ↵
                               // API you’re accessing is set to
    port: 80,                  // optional, default is 80
    path: '/path/to/api'       // optional, default is '/bustime/api/v1'
}

var bustime = require('bustime')(apiObj);

Request methods

There are two ways to make requests to the API using this library:

  1. Using an endpoint-specific method: This is the preferred way if you’d like to use the added services that bustime offers for each. For example, all endpoint-specific methods validate your request parameter object by default according to the needs of that endpoint, to avoid faulty requests made to the API (this can be turned off by on a per-method basis). Additionally, some of the methods offer special services that you can choose to turn on.
  2. Using the generic .request() method: This method makes a request to the API and converts the XML response into a JavaScript object. It offers nothing more than that. This is the method that each of the dedicated methods described above use to make requests between validating and performing additional services on the resulting data.

1. Endpoint-specific methods

Below are the methods dedicated to specific endpoints on the BusTime API. Each has its own request object requirements. This object (sans the services property pertaining to bustime’s services) is translated directly to the querystring in the request to the API. See the BusTime Developer API Guide for more information on each parameter.

A note on validation: Each endpoint-specific method below validates your reqObj object by default. When your object fails validation, an error is returned to your callback and the request to the BusTime API is aborted. To turn off validation (not that you’d ever want to), include a validate property set to false within the services property of your request object, like so:

var reqObj = {
  // ... your other properties ... //
  services: {
    validate: false
  }
}

I’ve omitted the validate property from the descriptions below for the sake of being succinct. Just know that it’s available in each of these endpoint-specific methods.

.time(reqObj, callback)

var reqObj = {
  services: {
    moment: true // optional
  }
}

bustime.time(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Services available:

result is an object with a tm property containing the API’s time in YYYYMMDD HH:MM:SS format, and an error property containing an array of errors. Like so:

{ tm: '20141127 10:07:30',
  moment:
   { _isAMomentObject: true,
     _i: '20141127 10:07:30',
     _f: 'YYYYMMDD HH:mm:ss',
     _isUTC: false,
     _pf:
      { empty: false,
        unusedTokens: [],
        unusedInput: [],
        overflow: -1,
        charsLeftOver: 0,
        nullInput: false,
        invalidMonth: null,
        invalidFormat: false,
        userInvalidated: false,
        iso: false },
     _locale:
      { _ordinalParse: /\d{1,2}(th|st|nd|rd)/,
        ordinal: [Function],
        _abbr: 'en',
        _ordinalParseLenient: /\d{1,2}(th|st|nd|rd)|\d{1,2}/ },
     _d: Thu Nov 27 2014 10:07:30 GMT-0500 (EST) } }

.vehicles(reqObj, callback)

var reqObj = {
  rt: route_number, // optional, not available w/vid
  vid: vehicle_id,  // optional, not available w/rt
  tmres: resolution // optional, defaults to 'm'
}

bustime.vehicles(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a vehicle property containing an array of vehicle objects, and an error property containing an array of error objects.

Request object properties are:

.routes(reqObj, callback)

bustime.routes(null, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a route property containing an array of route objects, and an error property containing an array of error objects.

.directions(reqObj, callback)

var reqObj = {
  rt: route_number // required
}

bustime.directions(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a dir property containing an array of route direction strings, and an error property containing an array of error objects.

Request object properties are:

.stops(reqObj, callback)

var reqObj = {
  rt: route_number, // required
  dir: direction    // required
}

bustime.stops(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a stop property containing an array of stop objects, and an error property containing an array of error objects.

Request object properties are:

.patterns(reqObj, callback)

var reqObj = {
  rt: route_number, // optional, not available w/pid
  pid: direction    // optional, not available w/rt
}

bustime.patterns(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a ptr property containing an array of pattern objects, and an error property containing an array of error objects.

Request object properties are:

.predictions(reqObj, callback)

var reqObj = {
  stpid: stop_id,       // optional, not available w/vid
  rt: route_number,     // optional, requires stpid
  vid: vehicle_id,      // optional, not available w/stpid
  top: max_predictions, // optional, max number of predictions
  tmres: resolution     // optional, defaults to 'm'
  services: {
    calculateETA: true  // optional, defaults to false
  }
}

bustime.predictions(reqObj, function (err, result) {
    console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a prd property containing an array of prediction objects, and an error property containing an array of error objects. It may contain both properties, particularly when multiple routes or stops are sent in the query.

Request object properties are:

Services available:

.serviceBulletins(reqObj, callback)

var reqObj = {
  rt: route_number,     // required if stpid not specified
  rtdir: route_dir,     // optional, requires rt property
  stpid: stop_id        // required if rt not specified
}

bustime.serviceBulletins(reqObj, function (err, result) {
  console.log(JSON.stringify(result, null, 2));
});

Where result is an object with a sb property containing an array of bulletin objects, and an error property containing an array of error objects.

2. Generic request method

The generic request method offers a barebones API request and no special services. It is up to you to set the request type as a string in the first argument. Like the endpoint-specific methods, it responds with a JavaScript object.

The generic .request() method might come in handy if you write your own BusTime-related methods and want to make them available for more than one API request type (as opposed to limiting your method to, for example, only predictions or only stops, for example). It could also be useful if a future version of BusTime adds endpoints that this library doesn’t yet cover.

.request(requestType, reqObj, callback)

var reqObj = {}; // The contents of this object will depend on the type ↵
                 // of request you’ll be making to the BusTime API.

var requestType = 'getpredictions'; // requires one of the BusTime request types

bustime.request(requestType, reqObj, function (err, result) {
  console.log(JSON.stringify(result, null, 2));
});

Where result is an object like the one you would get from any of the endpoint-specific methods described above.

Options for requestType are: 'gettime', 'getvehicles', 'getroutes', 'getdirections', 'getstops', 'getpatterns', 'getpredictions', 'getservicebulletins'.

Utility methods

bustime also offers a method for collecting data from the BusTracker API to store in memory or commit to a file for later use in your app. There is only one such method at the moment, but more may be added in the future. Open an issue if there’s a specific utility you’d like to see implemented.

.collectRoutesAndStops(callback[, config])

This method builds a comprehensive object which includes all available routes, their directions, and every stop served by each direction in each route. This can be useful if your application needs to check whether a specific stop (or group thereof) is served by a route, or rule out a stop depending on which direction a bus is going. All information associated with routes and stops is included and left intact to make the object as useful as possible.

By default, this method provides an array of route objects. That array looks like this:

[
  { rt: '1',
    rtnm: '1 ALTON PARK',
    rtclr: '#cc3399',
    dir: [
      { id: '0',
        stops: [
          { stpid: '1581',
            stpnm: '33RD + CHATTEM',
            lat: '35.017467535463',
            lon: '-85.321669578552'
          },
          { ... }
        ]
      },
      { id: '1',
        stops: [
          { ... },
          { ... }
        ]
      }
    ]
  },
  {
    rt: '2',
    ...
  }
]

The direction id is set to whatever is returned by your BusTracker API. It can be a number, but also something like 'Inbound'. This depends on how your BusTracker API is set up to identify route directions.

Alternatively, you could pass a config object as a second argument setting the format to 'object'. This config argument and the resulting object look like this:

var config = {
  format: 'object'
}

// Produces a slightly different object:
{
  '1': {
    rt: '1',
    rtnm: '1 ALTON PARK',
    rtclr: '#cc3399',
    dir: [ 
      { ... },
      { ... }
    ]
  }
}

Note the key:value pairs, making it easy to reference a specific route’s data by using the route number as the key. Other than this one feature, each route’s object is identical to the ones in the array format. This formatting option just gives you a different way of referencing the resulting object.

Please note: In either case, this operation can take a while to complete (up to a few seconds, depending on your API server’s load), so it’s recommended that you run this once while booting up your app (to store in memory) or as part of a data collection script (from which you can commit it to a text file or database for later consumption). Otherwise, you risk performance issues in your application.

What about the browser?

I’ll be working on making this work in the browser as well. No idea when, though. For the time being, browserify might do the trick (untested). Pull requests are welcome!