restbus Serverlisten([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 APIThe restbus API is bound by the same usage limits as the
NextBus XML feed. You've been warned.
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.
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:
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.
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.
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.
Returns an array of available transit agencies.
xml feed correspondence: command=agencyList
sample response: GET /agencies
Returns an agency object for transit agency id :agency.
xml feed correspondence: none
sample response: GET /agencies/sf-muni
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/sf-muni/routes
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/sf-muni/routes/F
Returns an array of all vehicles (buses) operated by transit agency id :agency.
xml feed correspondence: none
sample response: GET /agencies/sf-muni/vehicles
Returns a vehicle object for transit agency id :agency and vehicle id :vehicle.
xml feed correspondence: none
sample response: GET /agencies/sf-muni/vehicles/1074
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/sf-muni/routes/F/vehicles
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/sf-muni/routes/F/stop/5650/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,
F:5650, or N:6997. You can turn these two route:stop pairs into the tuple 'F:5650,N:6997'.
xml feed correspondence: command=predictionsForMultiStops
sample response: GET /agencies/sf-muni/tuples/F:5650,N:6997/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/sf-muni/stops/15650/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
The restbus API can return several kinds of HTTP error status codes:
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.