DOCSEARCHbyAlgolia
Submit Docs

OneBusAway Application Suite

repository·main·Indexed 42 days ago

https://github.com/onebusaway/onebusaway-application-modules

A platform for sharing real-time public transit information, featuring a REST API, GTFS-realtime data exports, and web interfaces like Wayfinder. Includes documentation for the API Key CLI v2.7.1, server setup via Docker, and configuration for GTFS and SIRI data sources.

Tokens
67.2K
Snippets
157
Records
228
Agent score
53%

What's inside OneBusAway

  1. Overview of OneBusAway Web interfaces

    main

    OneBusAway provides multiple web-based interfaces tailored to different user needs and device capabilities:

    • Standard Web Interface: The primary method for riders to access transit information. It includes a map view for finding nearby stops, route searching, and detailed stop pages. Stop pages provide real-time arrival/departure information, full schedules, and route filtering. Users can also drill down into complete transit trip details.
    • Text-Only Interface: A lightweight, text-only interface designed for basic web browsers on feature phones.
    • Mobile Web Interface: A custom interface optimized for modern mobile browsers with enhanced capabilities.

  2. Overview of the OneBusAway Application Suite

    main

    The OneBusAway application suite provides real-time public transit information through several interfaces:

    • Wayfinder: A high-performance web application built with SvelteKit.
    • OneBusAway Web: Includes standard web interfaces, Sign-mode (large format displays), mobile-optimized versions, and text-only versions.
    • OneBusAway REST API: A RESTful web service powering iOS, Android, and Alexa applications.
    • OneBusAway GTFS-realtime export: A bulk export of trip updates, vehicle positions, and service alerts in GTFS-realtime format.
    • OneBusAway Watchdog: A module for monitoring real-time data via web services.

  3. Use the OneBusAway Search API for autocomplete

    main

    The OneBusAway Search API provides endpoints that can be used to power autocomplete controls in transit applications. The API follows standard RESTful conventions.

    Supported search types include:

    • stop: Search for transit stops.
    • route: Search for transit routes.

    Detailed documentation for each specific search method can be found in their respective API reference pages (e.g., stop.html or route.html).

  4. Identify which modules require database configuration

    main

    Different OneBusAway modules use databases for different purposes. Depending on your deployment, you may need to provide a data-sources.xml for the following:

    User Management (onebusaway-users)

    Used to manage user account information. This is required if you are running any of the major UI modules:

    • onebusaway-sms-webapp
    • onebusaway-phone-webapp
    • onebusaway-webapp

    Transit Data Federation (onebusaway-transit-data-federation)

    Used to archive transit data. The onebusaway-transit-data-federation-webapp container requires a data-sources.xml pointing to your transit data database (typically the same database used for your transit data bundle).

  5. Deprecated: Plan a trip with plan-trip

    main

    WARNING: This method is deprecated and no longer supported.

    For multimodal trip planning capabilities, use the OpenTripPlanner open-source project instead.

    Historically, the plan-trip method allowed planning trips using public transit between locations, providing detailed sequences of steps including walking and transit legs. It used various parameters to favor specific types of trip plans based on user preferences (e.g., walking vs. waiting vs. transferring).

  7. Overview of the GTFS-RT Matching Perf Harness

    main

    The GTFS-RT Matching Perf Harness is a performance testing tool designed to reproduce the OneBusAway (OBA) GTFS-RT poll path at scale (specifically using King County Metro data). Its goal is to capture CPU and allocation profiles alongside wall-clock baselines to identify optimization tasks without modifying the core matching engine.

    Architecture

    The harness is implemented as a standalone Maven module, onebusaway-gtfsrt-perf, which includes a main() entry point that performs the following:

    1. Bundle Loading: Replicates the BundleLoader and AbstractGtfsRealtimeIntegrationTest wiring used in integration tests to load a pre-built KCM bundle.
    2. Execution Loop: Drives GtfsRealtimeSource.reset() and refresh() in a timed loop to ensure both the matching and block-location write stages are executed in every iteration.
    3. Profiling: Profiles the measure phase specifically.
    4. Regression Testing: Uses a unit-level golden test on GtfsRealtimeTripLibrary.createVehicleLocationRecordForUpdate to ensure behavior remains consistent during optimizations.

    Tech Stack

    • Runtime: Java 11, Spring 5.2 (non-Boot)
    • Build System: Maven multi-module
    • Profiling Tools: async-profiler (primary for macOS builds) with a programmatic JDK Flight Recorder (JFR) fallback.

  8. Handle list-based API responses in OneBusAway

    main

    Many OneBusAway API methods return a list of elements. When consuming these methods, you should account for the following request parameters and response elements:

    Request Parameters

    • maxCount: Controls the maximum number of elements returned in a single response. While you can override the default value, most methods enforce an upper limit regardless of the value provided.

    Response Elements

    • <list/>: The primary element containing the actual collection of results. The schema of the individual entries within this list depends on the specific API method being called.
    • <limitExceeded/>: A boolean value (true or false). It is true if the total number of available elements exceeded the maxCount provided (or the method's default maxCount).
    • <outOfRange/>: A boolean value indicating if the search request was made outside the current areas of service for OneBusAway. This is specifically included in geographic query methods such as:
      • routes-for-location
      • stops-for-location
      • trips-for-location

  9. Remap GTFS Agency IDs

    main

    When building bundles from multiple agencies, you can remap arbitrary GTFS agency IDs to specific IDs (such as APTA IDs) using the agencyIdMappings property in a GtfsBundle bean.

    You should also define a defaultAgencyId to handle GTFS elements (like stops or shapes) that lack an explicit agency assignment.

    <bean id="gtfsA" class="org.onebusaway.transit_data_federation.bundle.model.GtfsBundle">
    <property name="path" value="path/to/your/gtfs.zip" />
    <property name="defaultAgencyId" value="1" />
    <property name="agencyIdMappings">
        <map>
            <!-- Map GTFS Agency IDs to their APTA Agency Id -->
            <entry key="KCM" value="1" />
            <entry key="EOS" value="23" />
            <entry key="ST" value="40" />
        </map>
    </property>
</bean>

  10. Evaluate pre-match vehicle dedup in GtfsRealtimeSource

    main

    Currently, handleCombinedUpdates performs expensive matching for all feed updates before applying the _lastVehicleUpdate timestamp deduplication. This results in paying the full O(feed) match cost even when vehicles haven't changed.

    Task: Evaluate moving the deduplication gate earlier in the process.

    Risks and Considerations:

    • High Risk: Matching may have side effects (e.g., updating occupancy records, alerts, or MonitoredResult bookkeeping). Short-circuiting before matching might cause these updates to be dropped or stale predictions to persist.
    • Uncertainty: The current benchmark harness uses a pinned snapshot that forces every vehicle to look "changed" every iteration, so the actual reward in a production environment (where change rates are lower) cannot be quantified by the current harness.

    Recommendation: Do not implement this as a quick fix. It requires deep semantic analysis of downstream state mutations and new integration tests in onebusaway-gtfsrt-integration-tests to ensure side effects are preserved.

    Location: GtfsRealtimeSource.java:711 (match call) vs :741 (dedup gate).

  11. Important notes for <arrivalAndDeparture/> consumers

    main

    When consuming <arrivalAndDeparture/> data, be aware of the following:

    • Trip ID Mismatch: The active trip contained in the <tripStatus/> element may differ from the tripId specified in the <arrivalAndDeparture/>. This occurs in blocks of trips where the vehicle is currently servicing a previous trip that links to the trip that will ultimately service the current stop.
    • Frequency-based Scheduling: To support legacy clients, for frequency-based scheduled trips, scheduledArrivalTime and scheduledDepartureTime are set to current time + headway.

  12. Understand the OneBusAway API response structure

    main

    All API responses are wrapped in a top-level response element containing metadata and the payload.

    Response Fields

    • version: Response version information.
    • code: A machine-readable response code:
      • 200: Success
      • 400: Invalid request parameter or error
      • 401: Missing or invalid application key
      • 404: Resource not found
      • 500: Service exception or error
    • text: A human-readable version of the code.
    • currentTime: Current system time on the API server (milliseconds since Unix epoch).
    • data: The actual response payload.

    Example XML Response

    <response>
  <version>2</version>
  <code>200</code>
  <text>OK</text>
  <currentTime>1270614730908</currentTime>
  <data>
    <references/>
    ...
  </data>
</response>