OneBusAway Quickstart Guide - Hillsborough-Transit-Authority/onebusaway-application-modules GitHub Wiki

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] (https://github.com/OneBusAway/onebusaway-application-modules/wiki).

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.

You must have Java installed to use OBA. Please install Java SE JDK 1.6 (i.e., Java 6), since other versions of Java (1.5, 1.7) seem to have problems with annotations used in OBA.

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.war 

To build the bundle, run the following:

java -Xmx1G -server -jar onebusaway-quickstart-assembly.war -build path/to/gtfs.zip path/to/created-transit-bundle

To run the application suite:

java -jar onebusaway-quickstart-assembly.war \
 -webapp \
 -gtfsRealtimeAlertsUrl=http://www.bart.gov/dev/gtrtfs/alerts.aspx \
 -gtfsRealtimeTripUpdatesUrl=http://www.bart.gov/dev/gtrtfs/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.

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.

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.