Home

nextbusjs is a reasonable interface to the NextBus API written in Javascript. It works around a number of known issues with the service, allowing queries on routes and stops without the need for stopIds. It can gather the route and stop information and cache it, then perform queries based on this cached data. The cache can be ferried about, perhaps from a server to a client, in order to reduce loading time on the client interface.

Features

Route & Stop Predictions

Route and stop queries are run with the routePredict and stopPredict functions. They look like this:

function routePredict (route, direction, callback, units)
function stopPredict (stop, direction, callback, units)

These functions return an array of objects. Each object in the array is a single route or a single stop. It will have a title property and a predictions property. The predictions property will be an array of numbers or an array of objects if both is specified for the units.

Routes can be queried by tag and stops can be queried by title. Often times, a single stop is in the NextBus system as a couple of tags. nextbusjs attempts to remedy this situation by allowing queries based on the full title of the stop instead of the tag. If a full title is used, all of the tags with that title will be used in the query. (For those with an understanding of the NextBus public API, stopIDs are not used at all, as the author has found them to be highly unreliable.)

In summary: route predictions can be queried by tag; stop predictions can be queried by tag or by full title.

The data can be returned in minutes, seconds, or both, if desired:

nextbus.routePredict('a', null, callback, 'both');
// return looks like:
[
  {
    "title": "Scott Hall",
    "predictions": [
      {
        "minutes": "0", 
        "seconds": "47" 
      },   
      {
        "minutes": "4", 
        "seconds": "287"
      },   
      {
        "minutes": "12",
        "seconds": "767"
      },   
      {
        "minutes": "20",
        "seconds": "1247"
      },   
      {
        "minutes": "28",
        "seconds": "1727"
      }
    ]  
  },
  {
    "title": "Student Activities Center",
    "predictions": [
      {
        "minutes": "3", 
        "seconds": "206"
      },   
      {
        "minutes": "4", 
        "seconds": "298"
      },   
      {
        "minutes": "8", 
        "seconds": "538"
      },   
      {
        "minutes": "16",
        "seconds": "1018"
      },   
      {
        "minutes": "24",
        "seconds": "1498"
      }
    ]  
  },
...

So, if 'both' is passed as the units (fourth parameter), each prediction in the predictions array will be an object with a property minutes and a property seconds. Otherwise, each prediction in the predictions array will be a number. If there are no predictions for a particular stop or route in a query, the predictions property will be null.

Guessing active routes & stops

The guessActive function will attempt to guess which routes and stops are active. The algorithm works like this:

1. Run a vehicleLocations query to find which routes are active.
2. Assume that every route with a running bus is active.
3. Assume that every stop on every running route is running.
4. Return the lists of assumed running stops & routes.

This can be used to compile a list of likely running stops and routes. If you're displaying a user a list of stops and routes, you can use this to guess which are active. The algorithm may be wrong, though it is unlikely; so, be sure to allow the user to toggle the display of assumed-inactive routes.

The function looks like this:

function guessActive (callback)

The callback function is called with an object with two properties: routes and stops. It looks like this:

{ routes:                                                                     
   [ { tag: 'a', title: 'A' },
     { tag: 'b', title: 'B' },
     { tag: 'c', title: 'C' },
     { tag: 'ee', title: 'EE' },
     { tag: 'f', title: 'F' },
     { tag: 'h', title: 'H' },
     { tag: 'lx', title: 'LX' },
     { tag: 'w1', title: 'New Brunsquick 1 Shuttle' },
     { tag: 'w2', title: 'New Brunsquick 2 Shuttle' },
     { tag: 'rexb', title: 'REX B' },
     { tag: 'rexl', title: 'REX L' } ],
  stops: 
   [ { title: 'Allison Road Classrooms',
       geoHash: 'dr5n9904g74qm8n' },
     { title: 'Bravo Supermarket',
       geoHash: 'dr5n650x2u26hgn' },
     { title: 'Buell Apartments',
       geoHash: 'dr5n98y28hyu05z' },
     { title: 'Food Sciences Building',
       geoHash: 'dr5n60vwdpxz9hy' },
     { title: 'Liberty Street',
       geoHash: 'dr5n3gxfr067c9p' },
     { title: 'Library of Science',
       geoHash: 'dr5n93xdhrhym1m' },
     { title: 'Livingston Health Center',
       geoHash: 'dr5nd10d7u4f2pq' },
     { title: 'Livingston Plaza',
       geoHash: 'dr5nd177z7348nc' },
     { title: 'Livingston Student Center',
       geoHash: 'dr5nd1jp4prxtw0' },
     { title: 'Nursing School',
       geoHash: 'dr5n3gg2kf9fzqw' },
     { title: 'Paterson Street',
       geoHash: 'dr5n3gz9k0e7258' },
     { title: 'Public Safety Building North',
       geoHash: 'dr5n64d392w252w' },
     { title: 'Public Safety Building South',
       geoHash: 'dr5n646w1m1v1re' },
     { title: 'Rutgers Student Center',
       geoHash: 'dr5n3v3te15sj2t' },
     { title: 'Science Building',
       geoHash: 'dr5n990v1bfq7qm' },
     { title: 'Visitor Center',
       geoHash: 'dr5n3xd3z982508' },
     { title: 'Werblin Back Entrance',
       geoHash: 'dr5n984y3vrszwh' },
     { title: 'Werblin Main Entrance',
       geoHash: 'dr5n985ysdyzbkw' },
     { title: 'Zimmerli Arts Museum',
       geoHash: 'dr5n3uwzbhsuzx5' } ] }

The stops are sorted alphabetically for your convenience. This data is stored internally in the object and can be ferried about, then set with the function

function setActive (active)

where active is the object returned by guessActive.

Closest Stops Calculation

nextbusjs can attempt to detect what stops are near a lat / lon using geohashing. This isn't a very precise algorithm; it simply does string matching using the geohash. See geohash.js for the algorithm.

function closestStops (lat, lon, num, accuracy)

num is the number of stops you want returned. The accuracy is the minimum number of geohash characters which match. This query will be run against the 'active' data, if it has been loaded with guessActive. This will return an object of stop names mapped to accuracy:

{ 'Werblin Back Entrance': 6,
  'Hill Center': 6,
  'Buell Apartments': 6 }

Please don't hesitate to contact me with feature requests or bug reports. Thanks for checking out nextbusjs.