Skip to content

SIRI Element to UI mappings

Jump to bottom Edit New page
barbeau edited this page Nov 2, 2012 · 27 revisions

This page discusses how SIRI data element fields, especially the MonitoredVehicleJourney element, will be mapped to human-readable UI fields shown to transit riders in applications such as mobile apps. It is important to define these fields and the expected presentation to the transit rider so there is an understanding of data flow from transit agency real-time systems to OneBusAway (OBA) servers to mobile applications, which can all be implemented by separate parties, before the information actually reaches the transit rider.

We reference the General Transit Feed Specification (GTFS) on this page where SIRI elements and fields map to GTFS fields, since GTFS is a well-understood transit data spec that is used in many user-facing applications such as OneBusAway, Google Transit, OpenTripPlanner, and other applications.

Background

In the current OBA roadmap, we expect that the RESTful Mobile SIRI APIs (currently in use in MTA OBA-NYC) will replace the existing "Real-time APIs" in the onebusaway-api-webapp project. However, the OBA "Discovery APIs" for static transit information (generated from a GTFS feed) will remain in use. Some of the existing OBA API's provide a mix of real-time and "discovery" information; these will be partially deprecated.

A full description of what fields will be kept and which fields will be discarded is discussed in the RESTful API Roadmap.

SIRI Element to UI Mappings

We divide the SIRI elements and fields into three categories:

  1. Common fields - fields that appear in both distance and time-based SIRI user interfaces
  2. Distance-based fields - fields that appear in distance-based SIRI deployments (e.g., "your bus is one stop away")
  3. Time-based fields - fields that appear in time-based SIRI deployments (e.g., "your bus is 2 minutes and 30 seconds away")

It should be noted that an OBA server could generate both time and distance-based SIRI elements, in which case clients could show all 3 of the above categories of elements to end users.

As of September 2012, MTA's Bus Time system, based on OBA software, is the only production deployment of the OBA SIRI APIs. Currently, MTA's Bus Time system displays distance-based transit information rather than time-based information. As a result, we do not currently have a working implementation of a SIRI time-based interface to test against.

We use the format of:

Element.Field -> Description of field in user interface

For example:

  • MonitoredVehicleJourney.PublishedLineName -> Same as GTFS routes.txt route_short_name field. Per GTFS routes.txt spec, this should be "The route_short_name contains the short name of a route. This will often be a short, abstract identifier like '32', '100X', or 'Green' that riders use to identify a route, but which doesn't give any indication of what places the route serves."

This page may also contain field descriptions that are not directly shown to the user, but are necessary for a mobile application to logically organize data that will be presented to the user.

An example of a field that's not user-facing, but is necessary for organizing user-facing data:

  • MonitoredVehicleJourney.LineRef -> Same as GTFS routes.txt route_id field. Per GTFS routes.txt spec, "The route_id field contains an ID that uniquely identifies a route. The route_id is dataset unique." Not intended to be customer-facing. Customer-facing route descriptions should use MonitoredVehicleJourney.PublishedLineName, which is analogous to routes.txt route_short_name, or MonitoredVehicleJourney.DestinationName, which is analogous to routes.txt route_long_name.

Common fields

These fields are common to both Distance-based and Time-based SIRI deployments:

  • MonitoredVehicleJourney.LineRef -> Same as GTFS routes.txt route_id field. Per GTFS routes.txt spec, "The route_id field contains an ID that uniquely identifies a route. The route_id is dataset unique." Not intended to be customer-facing. Customer-facing route descriptions should use MonitoredVehicleJourney.PublishedLineName, which is analogous to routes.txt route_short_name, or MonitoredVehicleJourney.DestinationName, which is analogous to routes.txt route_long_name.

  • MonitoredVehicleJourney.OperatorRef -> Same as GTFS routes.txt agency_id field. Per GTFS routes.txt spec, "The agency_id field defines an agency for the specified route. This value is referenced from the agency.txt file. Use this field when you are providing data for routes from more than one agency."

  • MonitoredVehicleJourney.PublishedLineName -> Same as GTFS routes.txt route_short_name field. Per GTFS routes.txt spec, this should be "The route_short_name contains the short name of a route. This will often be a short, abstract identifier like '32', '100X', or 'Green' that riders use to identify a route, but which doesn't give any indication of what places the route serves."

  • MonitoredVehicleJourney.DestinationName -> Same as GTFS routes.txt route_long_name field. Per GTFS routes.txt spec, "The route_long_name contains the full name of a route. This name is generally more descriptive than the route_short_name and will often include the route's destination or stop. If the route does not have a long name, please specify a route_short_name and use an empty string as the value for this field."

TODO - finish these fields

Distance-based fields

These fields are specific to Distance-based SIRI deployments:

  • MonitoredVehicleJourney.MonitoredCall.Extensions.Distances.CallDistanceAlongRoute -> The distance of the stop from the beginning of the trip/route in meters, such as 3267.1.

  • MonitoredVehicleJourney.MonitoredCall.Extensions.Distances.DistanceFromCall -> The distance from the vehicle to the stop along the route in meters, such as 1329.9.

  • MonitoredVehicleJourney.MonitoredCall.Extensions.Distances.PresentableDistance -> The distance of a vehicle from a stop shown to a user, such as 6 stops away. MTA's logic that determines whether stops or miles are shown in the PresentableDistance field is below:

    • Show distance in miles if and only if:
      • (distance in miles to _immediate next stop_ is > D) OR (distance in stops to current stop is > N AND distance in miles to current stop > E)
    • In other words, show distance in stops if and only if (the below is just the inverse of the above, according to DeMorgan's law):
      • (distance in miles to _immediate next stop_ is <= D) AND (distance in stops to current stop <= N OR distance in miles to current stop <= E)
    • Show "approaching" if and only if:
      • distance_in_miles to immediate next stop < P
    • Show "at stop" if and only if:
      • distance_in_miles to immediate next stop < T
    • Current Parameter Values:
      • Parameter - Value
        • D - .5 miles
        • N - 3 stops
        • E - .5 miles
        • P - 500 feet
        • T - 100 feet

  • MonitoredVehicleJourney.MonitoredCall.Extensions.Distances.StopsFromCall -> The number of stops on the vehicle's current trip until the stop in question, starting from 0, such as 6.

Time-based fields

These fields are specific to Time-based SIRI deployments:

  • MonitoredVehicleJourney.MonitoredCall.ExpectedArrivalTime -> The predicted arrival time.

  • MonitoredVehicleJourney.MonitoredCall.ExpectedDepartureTime -> The predicted departure time.

  • MonitoredVehicleJourney.MonitoredCall.AimedArrivalTime -> The scheduled arrival time.

  • MonitoredVehicleJourney.MonitoredCall.AimedDepartureTime -> The scheduled departure time.

  • MonitoredVehicleJourney.Monitored -> false if the vehicle/trip in question is not actually being tracked (presumably this is used if you are showing scheduled-only values), true if it is being tracked.

  • MonitoredVehicleJourney.Delay -> The bus's deviation from schedule, in a format per XML conventions. For example, <Delay>P0Y0M0DT0H0M15S</Delay>.

References

Add a custom footer
Add a custom sidebar
Clone this wiki locally