SIRI VehicleMonitoring Call
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.
SIRI VehicleMonitoring Requests
It is accessible at the following URLs:
https://bustime.mta.info/api/siri/vehicle-monitoring.json
Please note that the calls made without either a VehicleRef or LineRef produces quite a load on the system, so use them sparingly. Any developers found to be making repeated calls (e.g. at less than 30 second intervals) for all vehicles in the system may find their key revoked.
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 MTA.
- VehicleRef - 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 - a filter by 'fully qualified' route name, GTFS agency ID + route ID (optional).
- DirectionRef - a filter by GTFS direction ID (optional). Either 0 or 1.
- VehicleMonitoringDetailLevel - 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.
- MaximumNumberOfCallsOnwards Limit on the number of OnwardCall elements for each vehicle when VehicleMonitoringDetailLevel=calls
- 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)
SIRI VehicleMonitoring 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>
