restbus Server
listen([port|callback],[callback])
Start the restbus server passing an optional port and/or listening callback. port defaults to 3535.
For example:
Now your application can access the restbus API over http://localhost:3535.
middleware()
Returns the restbus API as express middleware. See the example in listen() for usage.
close()
You won't really need this.*
Nevertheless, this stops restbus from accepting new connections while keeping existing ones until they are finished or time out. It's a wrapper for Node.js server.close() that doesn't accept a callback, and can only be invoked once until you restart your application, but you can restbus.listen() after calling close().
isListening()
Again, you won't really need this.*
Except maybe for testing or if you do want to restbus.close() for some reason and later see if restbus has stopped listening.
restbus API
The restbus API is bound by the same usage limits as the NextBus XML feed. You've been warned.
Standard Response Headers
All responses include a Content-Type: application/json header, and optionally a Content-Encoding: gzip header provided the corresponding Accept-Encoding: gzip request header.
restbus supports CORS by default and all API responses include an Access-Control-Allow-Origin: * header. Any CORS preflight request will return the other Access-Control-Allow-* headers.
All successful requests include an HTTP/1.1 200 OK status header in the response.
HATEOAS Guidelines
The restbus API does not adhere to any IETF standard for general resource linking because there is none. Moreover, restbus does not use any of the many popular JSON linking strategies (or their associated media types) like HAL, JSON-LD, JSON-Schema etc., because they don't appear to be on the IETF Standards Track for acceptance (yet).
Therefore, the restbus approach to JSON linking strives to meet RFC 5988 Web Linking specifications as much as possible.
The restbus API adheres to the HATEOAS requirement of REST. Each resource has a restbus hypertext _links property that was influenced by mnot's linking in JSON article, and is structured closely to the RFC 5988 specification for Web Linking. It's very similiar to a JSON serialization of Web Links grouped into the "state transitions" described below.
The _links property has the following structure:
Link Object
Every _links "state transition" key is (self) or has (to, from) link objects with attributes describing the link's target resource. restbus link objects use the following attributes as defined directly from RFC 5988 Target Attributes:
type: A hint at the expected media type of the target resource.rel: The link relation between resources.title: A human readable description of the target resource.
In addition, link objects also use the following attributes:
href: The URI to follow when dereferencing the link. This is the hyperlink, an analogue to a web link's Target IRI (URI).rt: The target's resource type, as defined by RFC 6690.
Clients may perform an HTTP OPTIONS request and inspect the HTTP Allow response header for supported HTTP methods. Currently, restbus only supports HTTP GET requests.
If the restbus API ever supports media types other than application/json, and/or HTTP methods other than GET, link objects will add support for a "hints" attribute as specified by HTTP Link Hints.
Link Relation
Every link object has one rel attribute. All link relation values are taken directly from RFC 5988's initial registry contents, with the exception of one extension relation type, "full", which was borrowed from JSON Hyper-Schema (replaced with item).
Here is a full example of restbus API hypertext _links for an agency resource:
A client can discover representations for all restbus resources via _links without relying on the documentation below, although the documentation below is sure to help.
Agencies
GET /agencies
Returns an array of available transit agencies.
xml feed correspondence: command=agencyList
sample response: GET /agencies
GET /agencies/:agency
Returns an agency object for transit agency id :agency.
xml feed correspondence: none
sample response: GET /agencies/omnitrans
Routes
GET /agencies/:agency/routes
Returns an array of routes serviced by transit agency id :agency. The route objects in this response contain very limited information and are meant to be used for building UI <select>'s of an agencies available routes. For more detailed route information use the routeconfig endpoint below.
xml feed correspondence: command=routeList
sample response: GET /agencies/omnitrans/routes
GET /agencies/:agency/routes/:route
Returns a route configuration object for transit agency id :agency with route id :route. The route configuration data contains more detailed information for a route as well as arrays of the stop, direction, and path objects that constitute the route. Route configuration data can be complex. For more detailed information about the properties of each object, see the NextBus XML feed documentation under "Command routeConfig", and view the sample response below.
xml feed correspondence: command=routeConfig
sample response: GET /agencies/omnitrans/routes/1
Vehicles (Buses)
GET /agencies/:agency/vehicles
Returns an array of all vehicles (buses) operated by transit agency id :agency.
xml feed correspondence: none
sample response: GET /agencies/omnitrans/vehicles
GET /agencies/:agency/vehicles/:vehicle
Returns a vehicle object for transit agency id :agency and vehicle id :vehicle.
xml feed correspondence: none
sample response: GET /agencies/omnitrans/vehicles/1347
GET /agencies/:agency/routes/:route/vehicles
Returns an array of all vehicles operated by transit agency id :agency and currently on route id :route.
xml feed correspondence: command=vehicleLocations
sample response: GET /agencies/omnitrans/routes/1/vehicles
Predictions
GET /agencies/:agency/routes/:route/stops/:stop/predictions
Returns an array of predictions for agency id :agency, route id :route and stop id :stop. Each prediction object contains an array of 'values' which is most likely the data you want. The array of values in sorted in ascending order by the 'epochTime' property.
xml feed correspondence: command=predictions
sample response: GET /agencies/omnitrans/routes/1/stop/5303/predictions
GET /agencies/:agency/tuples/:tuple/predictions
Returns an array of predictions, one for each route:stop pair in the :tuple for agency id :agency. A tuple is a set of route:stop pairs separated by commas (,). A route:stop pair is a :route and :stop separated by a colon (:). For example, 1:5303, or 2:5423. You can turn these two route:stop pairs into the tuple '1:5303,2:5423'.
xml feed correspondence: command=predictionsForMultiStops
sample response: GET /agencies/omnitrans/tuples/1:5303,2:5423/predictions
GET /agencies/:agency/stops/:code/predictions
Returns an array of predictions for all routes passing through the stop with code :code for agency id :agency. Not all transit agencies use stop codes.
xml feed correspondence: command=predictionsForMultiStops (replaced 'stopId' with 'code')
sample response: GET /agencies/omnitrans/stops/5303/predictions
GET /locations/:latlon/predictions†
Returns an array of predictions for all stops within a set radius of a latitude and longitude :latlon. The radius is set at 2,300 meters or about 1.5 miles. Predictions can be spread across multiple agencies depending on :latlon. This endpoint sorts the array of 'values' in ascending order, but using 'minutes' instead because 'epochTime' is always null due to unavailability. :latlon has the form latitude,longitude, e.g '37.784825,-122.395592'.
xml feed correspondence: none
sample response: GET /locations/37.784825,-122.395592/predictions
Errors
The restbus API can return several kinds of HTTP error status codes:
- 404 Not Found
- 405 Method Not Allowed
- 500 Internal Server Error
- 503 Service Unavailable
404 status indicates an unsupported URL was requested. Check your URL structure.
405 status indicates a client tried to use an unsupported HTTP method.
503 status corresponds to an "initializing" error response from the NextBus XML feed, and clients are encouraged to try the request until initialization is complete. You should rarely encounter this status code.
500 status is most likely some networking error when requesting data from webservices.nextbus.com, however it could also be due to an XML parsing error. Check the message property of the error response object for more information. You should rarely, if ever, encouter this status code.
An error looks like:
* These were added purely for demonstration and are not of much use in a production environment.
† This endpoint is experimental as it relies on a NextBus Inc. data source that may be removed at any time without warning or notice. Use it at your own risk.