Stop Monitoring

SIRI StopMonitoring Call

The SIRI StopMonitoring ("SIRI SM") call allows the developer to request 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 for the B63.

SIRI StopMonitoring Requests

It is accessible at the following URLs:

https://bustime.mta.info/api/siri/stop-monitoring.json

with the following GET parameters:

  • key - your MTA Bus Time developer API key (required). Go here to get one.
  • version - which version of the SIRI API to use (1 or 2). Defaults to 1, but 2 is preferrable.
  • OperatorRef - the GTFS agency ID to be monitored (optional). Currently, all stops have operator/agency ID of MTA. If left out, the system will make a best guess. Usage of the OperatorRef is suggested, as calls will return faster when populated.
  • MonitoringRef - 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 - a filter by 'fully qualified' route name, GTFS agency ID + route ID (e.g. MTA NYCT_B63).
  • DirectionRef - a filter by GTFS direction ID (optional). Either 0 or 1.
  • StopMonitoringDetailLevel - Level of detail present in response. In order of verbosity:
    minimum - only available in version 2. Designed for front-end use.
    basic - only available in version 2. Designed for system-to-system interchange when GTFS is loaded.
    normal - default.
    calls 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).
  • MaximumNumberOfCallsOnwards - Limits the number of OnwardCall elements returned in the query.
  • MaximumStopVisits - an upper bound on the number of buses to return in the results.
  • MinimumStopVisitsPerLine - a lower bound on the number of buses to return in the results per line/route (assuming that many are available)

An example URL, incorporating some of these GET parameters, is https://bustime.mta.info/api/siri/stop-monitoring.json?key=##KEY##&OperatorRef=MTA&MonitoringRef=308209&LineRef=MTA%20NYCT_B63

SIRI StopMonitoring Responses

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.