OneBusAway Quickstart Guide
The OneBusAway (OBA) application suite makes it easy to integrate GTFS and GTFS-realtime data into a unified bundle that can power webapps, mobile apps through a REST API, SMS and phone interface, and large displays. For more information on OBA features, see the OBA application suite documentation.
In this tutorial, we'll show you how you can be up and running in five minutes with your data and OBA without having to edit any code.
EDIT October 13, 2021
OneBusAway has upgraded to v2.0.
- v2 website examples - Puget Sound, WMATA in Washington, D.C. and HART in Tampa, FL
The below QuickStart instructions are for version v1.x, which is outdated. Components like the web interface in v1 may not work.
The QuickStart feature for v2.x (current master branch) is still under development. However, if you'd like to get v2.0 up and running quickly, you might want to check out this Docker image.
You must have Java installed to use OBA. We recommend Java SE JDK 1.7 (i.e., Java 7) or higher.
(NOTE: OBA 1.1.13 and higher is compatible with both Java 6 and 7, while OBA 1.1.11 and earlier are only compatible with Java 6)
The first step is to download the latest OneBusAway Quick-Start Java Application. Pick an application based on what features you are interested in:
- The full webapp (includes the REST API and the web interfaces) - onebusaway-quickstart-assembly-webapp.war
- The API-only webapp (no web user interface, just the REST API) - onebusaway-quickstart-assembly-api-webapp.war
In our example, we'll use the API-only webapp.
To run the quick-start, you will need both a GTFS feed and a GTFS-realtime feed from a transit system.
For our quick-start, we'll use BART's GTFS feed and BART's GTFS-realtime feed.
Running OneBusAway is a two-step process:
- Build a transit data bundle: raw transit data is processed into an optimized bundle, geared for fast access.
- Run the OneBusAway webapp: actually start the OneBusAway web applications, using the transit data bundle.
You can perform these two steps either using our simple GUI configuration tool or from the command-line.
We provide a simple wizard to help you configure and run the OneBusAway quick-start application. Simply double-click the downloaded quick-start war file. Follow the steps and you'll be up and running in no time.
NOTE: You may need to run the OneBusAway quick-start GUI from the command-line if you want to pass additional options to java, like specifying more memory or server optimization:
java -Xmx1G -server -jar onebusaway-quickstart-assembly-1.1.19-api-webapp.war
To build the bundle, run the following:
java -Xmx1G -server -jar onebusaway-quickstart-assembly-1.1.19-api-webapp.war -build path/to/gtfs.zip path/to/created-transit-bundle
To run the application suite:
java -jar onebusaway-quickstart-assembly-1.1.19-api-webapp.war \
-webapp \
-gtfsRealtimeAlertsUrl=http://api.bart.gov/gtfsrt/alerts.aspx \
-gtfsRealtimeTripUpdatesUrl=http://api.bart.gov/gtfsrt/tripupdate.aspx \
path/to/created-transit-bundle
This specifies that GTFS-realtime alerts and trip-updates should be pulled from the BART GTFS-realtime feeds. If everything goes well, you can now start making calls to the OneBusAway REST API, which is discussed below.
By default the server will start on port 8080. If you'd like to change this, you can use the -port=XX command line parameter, like:
java -Xmx1G -server -jar onebusaway-quickstart-assembly-1.1.19-api
-webapp.war -webapp bundle -port=80
The REST API should now be up and running, so you can query the OBA REST API for a variety of transit information via pasting the below URLs into your web browser.
We suggest you first start by retrieving the set of agencies supported in your OneBusAway instance using the agencies-with-coverage method:
http://localhost:8080/api/where/agencies-with-coverage.json?key=TEST
{"code":200,
"currentTime":1441719853231,
"data":{
"limitExceeded":false,
"list":[
{"agencyId":"Hillsborough Area Regional Transit",
"lat":27.976910500000002,
"latSpan":0.5424609999999994,
"lon":-82.445851,
"lonSpan":0.576357999999999}],
"references":{
"agencies":[
{"disclaimer":"",
"id":"Hillsborough Area Regional Transit",
"lang":"en",
"name":"Hillsborough Area Regional Transit",
"phone":"813-254-4278",
"privateService":false,
"timezone":"America/New_York",
"url":"http://www.gohart.org"}
],"
routes":[],"situations":[],"stops":[],"trips":[]}},"text":"OK","version":2}
Retrieve the set of stops near a location using the stops-for-location method:
http://localhost:8080/api/where/stops-for-location.xml?key=TEST&lat=37.785045&lon=-122.407049
<?xml version="1.0"?>
<response>
<version>2</version>
<code>200</code>
<currentTime>1330945230362</currentTime>
<text>OK</text>
<data class="listWithRangeAndReferences">
<references>...</references>
<list>
<stop>
<id>BART_MONT</id>
<lat>37.7893359611</lat>
<lon>-122.401485489</lon>
<name>Montgomery St. BART</name>
<code>MONT</code>
<locationType>0</locationType>
<routeIds>
<string>BART_12</string>
<string>BART_06</string>
...
</routeIds>
</stop>
<stop>
<id>BART_POWL</id>
<lat>37.7849710021</lat>
<lon>-122.407012285</lon>
<name>Powell St. BART</name>
<code>POWL</code>
<locationType>0</locationType>
<routeIds>
<string>BART_12</string>
<string>BART_06</string>
...
</routeIds>
</stop>
</list>
<limitExceeded>false</limitExceeded>
<outOfRange>false</outOfRange>
</data>
</response>
Retrieve the set of real-time arrivals and departures at a particular stop using the arrivals-and-departures-for-stop method:
http://localhost:8080/api/where/arrivals-and-departures-for-stop/BART_POWL.xml?key=TEST
<?xml version="1.0"?>
<response>
<version>2</version>
<code>200</code>
<currentTime>1330945364170</currentTime>
<text>OK</text>
<data class="entryWithReferences">
<references>
...
<situations>
<situation>
<id>BART_BSA_94422</id>
<creationTime>1330899176218</creationTime>
<reason>MAINTENANCE</reason>
<allAffects>
<affects>
<agencyId>BART</agencyId>
</affects>
</allAffects>
<consequences>
<consequence>
<condition>significant_delays</condition>
</consequence>
</consequences>
</situation>
</situations>
</references>
<entry class="stopWithArrivalsAndDepartures">
<stopId>BART_POWL</stopId>
<arrivalsAndDepartures/>
<nearbyStopIds/>
<situationIds>
<string>BART_BSA_94422</string>
</situationIds>
</entry>
</data>
</response>
If you deployed the full OneBusAway webapp Java application that contains the web user interfaces, you can open your browser to the below URL to see the interface:
http://localhost:8080/
To see more options for configuring the build and the webapp, including adding real-time information, specify the -help option to get full usage instructions:
java -jar onebusaway-quickstart-assembly.war -help
Also, check out the main OneBusAway Troubleshooting page.
If you want to get your hands dirty with the code, head over to the OBA Developer Guide for a tutorial on deploying the web applications discussed here from the source code using Eclipse.
Also, see how to configure OneBusAway to consume other other real-time transit data formats.