Skip to content

SIRI API

Jump to bottom Edit New page
Michael Frumin edited this page Jun 21, 2013 · 6 revisions

OneBusAway has a built-in API to process incoming SIRI-SX XML. The Bus CIS Server uses this for Stop Monitoring (the upcoming buses for a stop) and Vehicle Monitoring (The upcoming stops for a bus).

SM

The SIRI StopMonitoring (“SIRI SM”) call requests information about the vehicles serving a particular stop. As much as possible, the values used both in the SM request and the SM response correspond to the values in the GTFS data.

Call

{front-end URL}/api/siri/stop-monitoring.xml
{front-end URL}/api/siri/stop-monitoring.json

Options

_ URL Parameter _Example _Description
key xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Bus CIS Server developer API key
OperatorRef MTA the GTFS agency ID to be monitored (optional). Currently, all stops have operator/agency ID of MTA, but if you leave this parameter out the system will do its best to figure out what stop you are referring to
MonitoringRef 308214 the GTFS stop ID of the stop to be monitored (required). For example, 308214 for the stop at 5th Avenue and Union St towards Bay Ridge.
LineRef B63 filter by GTFS route ID
DirectionRef 0 filter by GTFS direction ID (optional). Either 0 or 1
StopMonitoringDetailLevel normal Determines whether or not the response will include the stops (“calls” in SIRI-speak) each vehicle is going to make after it serves the selected stop (optional). To get calls data, use value calls, otherwise use value normal (default is normal).
MaximumNumberOfCallsOnwards 1 Limits the number of OnwardCall elements returned in the query.
MaximumStopVisits 3 an upper bound on the number of buses to return in the results.
MinimumStopVisitsPerLine 1 a lower bound on the number of buses to return in the results per line/route (assuming that many are available)

Response

The XML below illustrates the SIRI StopMonitoring response. The comments in the XML below document the meaning of each of the XML elements that are unique to the SIRI StopMonitoring call. Much of the interesting data is contained inside the MonitoredVehicleJourney element, which has its own documentation.

Note that the MonitoredVehicleJourney of a SIRI SM call will always have a MonitoredCall element. The first OnwardCall element (if requested) will always be the next stop the bus will make, which in most cases is a stop before the MonitoredCall.

Other notes about the particularities of StopMonitoring data is shown after the example response.

<!-- SIRI container elements -->
<Siri version="1.3" xmlns="http://www.siri.org.uk/siri">
  <ServiceDelivery>


    <!-- The timestamp on the MTA Bus Time server at the time the request was fulfilled -->
    <ResponseTimestamp>2011-01-28T14:49:58-05:00</ResponseTimestamp>


    <!-- SIRI container for VehicleMonitoring response data -->
    <StopMonitoringDelivery version="1.3">


      <!-- Same as above.  Required by the SIRI spec. -->
      <ResponseTimestamp>2011-01-28T14:49:58-05:00</ResponseTimestamp>
      <!-- The time until which the response data is valid until. -->
      <ValidUntil>2011-01-28T14:50:58-05:00</ValidUntil>


      <!-- SIRI container for data about a particular vehicle service the selected stop -->
      <MonitoredStopVisit>


        <!-- The timestamp of the last real-time update from the particular vehicle -->
        <RecordedAtTime>2011-01-28T14:49:27-05:00</RecordedAtTime>


        <!-- A complete MonitoredVehicleJourney element. See the MonitoredVehicleJourney page for more information-->
        <MonitoredVehicleJourney>...</MonitoredVehicleJourney>


      </MonitoredStopVisit>


      ... More MonitoredStopVisit elements


    </StopMonitoringDelivery>
  </ServiceDelivery>
</Siri>

StopMonitoring Updates to Use Block-Level Assignment

StopMonitoring results will now include buses that are scheduled to stop at the monitored stop according to the schedule for their assigned blocks, even if they are not yet on the trip that will serve the monitored stop. This occurs only when those buses have a block-level assignment; otherwise, they are not included until they reach the terminal and present evidence that they will continue on to serve the monitored stop. In general, this means that StopMonitoring requests will have more results. The diagram below shows an example of this behavior.

This is indicated by:

  • The ProgressStatus field will include a prevTrip flag, indicating that the bus is still on a trip prior to the one that will serve the monitored stop. The prevTrip flag may also be combined with layover when the bus is laying over and scheduled to depart.
  • the OnwardCalls will start at the beginning of the trip on which the bus will serve the monitored stop. That means that the first OnwardCall will be often be more than 1 stop away.
    The FramedJourneyRef (which has the GTFS trip_id) being different for a given bus than in in the VehicleMonitoring result for that bus.

VM

The SIRI VehicleMonitoring (“SIRI VM”) call allows the developer to request information about one, some, or all vehicles monitored by the MTA Bus Time system. As much as possible, the values used both in the VM request and the VM response correspond to the values in the GTFS data.

Call

{front-end URL}/api/siri/vehicle-monitoring.xml
{front-end URL}/api/siri/vehicle-monitoring.json

Options

_ URL Parameter _Example _Description
key xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Bus CIS Server developer API key
OperatorRef MTA NYCT the GTFS agency ID to be monitored (optional). Currently MTA NYCT or MTABC
VehicleRef 7560 the ID of the vehicle to be monitored (optional). This is the 4-digit number painted on the side of the bus, for example 7560. Response will include all buses if not included
LineRef B63 filter by GTFS route ID
DirectionRef 0 filter by GTFS direction ID (optional). Either 0 or 1
VehicleMonitoringDetailLevel normal Determines whether or not the response will include the stops (“calls” in SIRI-speak) each vehicle is going to make after it serves the selected stop (optional). To get calls data, use value calls, otherwise use value normal (default is normal).
MaximumNumberOfCallsOnwards 1 Limits the number of OnwardCall elements returned in the query.

Responses

The XML below illustrates the SIRI VehicleMonitoring response. The comments in the XML below document the meaning of each of the XML elements that are unique to the SIRI VehicleMonitoring call. Much of the interesting data is contained inside the MonitoredVehicleJourney element, which has its own documentation.

<!-- SIRI container elements -->
<Siri version="1.3" xmlns="http://www.siri.org.uk/siri">
  <ServiceDelivery>


    <!-- The timestamp on the MTA Bus Time server at the time the request was fulfilled -->
    <ResponseTimestamp>2011-01-28T14:22:48-05:00</ResponseTimestamp>


    <!-- SIRI container for VehicleMonitoring response data -->
    <VehicleMonitoringDelivery version="1.3">


      <!-- Same as above.  Required by the SIRI spec. -->
      <ResponseTimestamp>2011-01-28T14:22:48-05:00</ResponseTimestamp>
      <!-- The time until which the response data is valid until. -->
      <ValidUntil>2011-01-28T14:23:48-05:00</ValidUntil>


      <!-- SIRI container for data about a particular vehicle -->
      <VehicleActivity>


        <!-- The timestamp of the last real-time update from the particular vehicle -->
        <RecordedAtTime>2011-01-28T14:22:30-05:00</RecordedAtTime>


        <!-- A MonitoredVehicleJourney element for a vehicle in revenue service. Please See the MonitoredVehicleJourney page for a thorough discription -->
        <MonitoredVehicleJourney>
          ...
        </MonitoredVehicleJourney>
      </VehicleActivity>


      <!-- The next vehicle. -->
      <VehicleActivity>
        <RecordedAtTime>2011-01-28T14:22:43-05:00</RecordedAtTime>


        <!-- A complete MonitoredVehicleJourney element. See the MonitoredVehicleJourney page for more information-->
        <MonitoredVehicleJourney>...</MonitoredVehicleJourney>
      </VehicleActivity>


      ... More VehicleActivity elements


    </VehicleMonitoringDelivery>
  </ServiceDelivery>
</Siri>

MonitoredVehicleJourney

The SIRI MonitoredVehicleJourney element contains most of the relevant real-time information about particular vehicles in the MTA Bus Time system. It is used by the responses to both the VehicleMonitoring. and StopMonitoring. calls. As much as possible, the values in a MonitoredVehicleJourney element correspond to the values in the MTA’s GTFS data.

The XML below illustrates the SIRI MonitoredVehicleJourney element. Other notes on the contents of a MonitoredVehicleJourney follow the example.

<MonitoredVehicleJourney>


  <!-- The GTFS route ID for the trip the vehicle is serving. Not intended to be customer-facing. -->
  <LineRef>B63</LineRef>


  <!-- The GTFS direction for the trip the vehicle is serving -->
  <DirectionRef>1</DirectionRef>


  <!-- A compound element uniquely identifying the trip the vehicle is serving -->
  <FramedVehicleJourneyRef>


    <!-- The GTFS service date for the trip the vehicle is serving -->
    <DataFrameRef>2011-01-28</DataFrameRef>


    <!-- The GTFS trip ID for trip the vehicle is serving, preceeded by the GTFS agency ID -->
    <DatedVehicleJourneyRef>MTA NYCT_20110102EA_087800_B63_0002_B63_19</DatedVehicleJourneyRef>
  </FramedVehicleJourneyRef>


  <!-- The GTFS Shape_ID, prefixed by GTFS Agency ID -->
  <JourneyPatternRef>MTA NYCT_B630152</JourneyPatternRef>


  <!-- The GTFS route_short_name -->
  <PublishedLineName>B63</PublishedLineName>


  <!-- GTFS Agency_ID -->
  <OperatorRef>MTA NYCT</OperatorRef>


  <!-- The GTFS stop ID for the first stop on the trip the vehicle is serving, prefixed by Agency ID  -->
  <OriginRef>MTA_801131</OriginRef>


  <!-- The GTFS stop ID for the last stop on the trip the vehicle is serving, prefixed by Agency ID -->
  <DestinationRef>MTA_801042</DestinationRef>


  <!-- The GTFS Route for the trip the vehicle is serving -->
  <DestinationName>BAY RIDGE SHORE RD via 5 AV</DestinationName>


  <!-- OriginAimedDepartureTime indicates the scheduled departure time of that bus from that terminal in ISO8601 format -->
  <OriginAimedDepartureTime>2011-01-28T14:45:00.000-04:00 </OriginAimedDepartureTime>


  <!-- SituationRef, present only if there is an active service alert covering this call -->
  <SituationRef>
    <SituationSimpleRef>MTA NYCT_8d065d76-2813-46ee-b024-20f956232831</SituationSimpleRef>
  </SituationRef>


  <!-- Always true -->
  <Monitored>true</Monitored>


  <!-- The most recently recorded or inferred coordinates of this vehicle -->
  <VehicleLocation>
    <Longitude>-73.97857</Longitude>
    <Latitude>40.68448</Latitude>
  </VehicleLocation>


  <!-- Vehicle bearing: 0 is East, increments counter-clockwise -->
  <Bearing>345.7</Bearing>


  <!-- Indicator of whether the bus is making progress (i.e. moving, generally) or not. -->
  <ProgressRate>normalProgress</ProgressRate>


  <!-- Indicator of vehicle progress status.  Set to "layover" when the bus is in a layover at a terminal, otherwise not present, and/or "prevTrip" when the bus is currently serving the previous trip. -->
  <ProgressStatus>layover</ProgressStatus>


  <!-- The vehicle ID, preceded by the GTFS agency ID -->
  <VehicleRef>MTA NYCT_7582</VehicleRef>


  <!-- Depending on the system's level of confidence, the GTFS block_id the bus is serving -->
  <BlockRef>MTA NYCT_20120902CE_JG_24900_B35-26-JG_1503</BlockRef>


  <!-- Call data about a particular stop -->
  <!-- In StopMonitoring, it is the stop of interest; in VehicleMonitoring it is the next stop the bus will make. -->


  <MonitoredCall>


    <!-- The GTFS stop ID of the stop prefixed by agency_id -->
    <StopPointRef>MTA_308214</StopPointRef>


    <!-- The ordinal value of the visit of this vehicle to this stop, always 1 in this implementation -->
    <VisitNumber>1</VisitNumber>


    <!-- SIRI container for extensions to the standard -->
    <Extensions>


      <!-- The MTA Bus Time extensions to show distance of the vehicle from the stop -->
      <Distances>


        <!-- The distance of the stop from the beginning of the trip/route  -->
        <CallDistanceAlongRoute>3038.9</CallDistanceAlongRoute>


        <!-- The distance from the vehicle to the stop along the route, in meters -->
        <DistanceFromCall>1101.7</DistanceFromCall>


        <!-- The distance displayed in the UI, see below for an additional note -->
        <PresentableDistance>5 stops away</PresentableDistance>


        <!-- The number of stops on the vehicle's current trip until the stop in question, starting from 0 -->
        <StopsFromCall>5</StopsFromCall>
      </Distances>
    </Extensions>


  </MonitoredCall>


  <!-- The collection of calls that a vehicle is going to make.  -->
  <OnwardCalls>


    <!-- A stop that the vehicle is going to make  -->
    <OnwardCall>


      <!-- The GTFS stop ID of the stop -->
      <StopPointRef>MTA_308215</StopPointRef>


      <!-- The ordinal value of the visit of this vehicle to this stop, always 1 in this implementation -->
      <VisitNumber>1</VisitNumber>


      <!-- The GTFS stop name of the stop -->
      <StopPointName>5 AV - GARFIELD PL</StopPointName>


      <!-- SIRI container for extensions to the standard -->
      <Extensions>


        <!-- The MTA Bus Time extensions to show distance of the vehicle from the stop -->
        <Distances>


          <!-- The distance of the stop from the beginning of the trip/route  -->
          <CallDistanceAlongRoute>3267.1</CallDistanceAlongRoute>


          <!-- The distance from the vehicle to the stop along the route, in meters -->
          <DistanceFromCall>1329.9</DistanceFromCall>


          <!-- The distance displayed in the UI -->
          <PresentableDistance>6 stops away</PresentableDistance>


          <!-- The number of stops on the vehicle's current trip until the stop in question, starting from 0 -->
          <StopsFromCall>6</StopsFromCall>
        </Distances>
      </Extensions>


    </OnwardCall>


    ... more OnwardCalls


  </OnwardCalls>
</MonitoredVehicleJourney>

The PresentableDistance field:
The 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 |

Transparency of Block vs. Trip-Level Assignment

The Bus CIS Server tries to assign buses to blocks- a sequence of trips that start and end at a depot. This allows the system to make a statement about what a bus will do after it reaches the end of its current trip.

However, there is not always enough affirmative and corresponding evidence to make such a strong statement. In this case, the Bus CIS Server falls back to a trip-level assignment, where it just picks a trip from the schedule that is representative of the route and stopping pattern that the bus is likely to pursue.

The SIRI API now reflects this distinction as described here and in other items below. If the assignment is block-level, the new BlockRef field of the MonitoredVehicleJourney is present, and populated with the assigned block id.

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