Wiki source code of SIRI StopMonitoring

Last modified by admin admin on 2023/09/13 12:54
Show last authors
1 = SIRI StopMonitoring Call =
2
3 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.
4
5 == SIRI StopMonitoring Requests ==
6
7 It is accessible at the following URLs:
8
9 https://bustime.mta.info/api/siri/stop-monitoring.json
10
11 with the following GET parameters:
12
13 * **key** - your MTA Bus Time developer API key (required). Go {{html}}<a href="https://spreadsheets.google.com/viewform?hl=en&formkey=dG9kcGIxRFpSS0NhQWM4UjA0V0VkNGc6MQ#gid=0">here</a>{{/html}} to get one.
14
15 * **version** - which version of the SIRI API to use (1 or 2). Defaults to 1, but 2 is preferrable.
16
17 * **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.
18
19 * **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.
20
21 * **LineRef** - a filter by 'fully qualified' route name, GTFS agency ID + route ID (e.g. MTA NYCT_B63).
22
23 * **DirectionRef** - a filter by GTFS direction ID (optional). Either ##0## or ##1##.
24
25 * **StopMonitoringDetailLevel** - Level of detail present in response. In order of verbosity:
26 ##minimum## - only available in version 2. Designed for front-end use.
27 ##basic## - only available in version 2. Designed for system-to-system interchange when GTFS is loaded.
28 ##normal## - default.
29 ##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).
30
31 * **MaximumNumberOfCallsOnwards** - Limits the number of ##OnwardCall## elements returned in the query.
32
33 * **MaximumStopVisits** - an upper bound on the number of buses to return in the results.
34
35 * **MinimumStopVisitsPerLine** - a lower bound on the number of buses to return in the results per line/route (assuming that many are available)
36
37 An example URL, incorporating some of these GET parameters, is {{html}}<a class="wikimodel-freestanding" href="https://bustime.mta.info/api/siri/stop-monitoring.json?key=##KEY##&OperatorRef=MTA&MonitoringRef=308209&LineRef=MTA%20NYCT_B63">
38 <span class="wikigeneratedlinkcontent">https://bustime.mta.info/api/siri/stop-monitoring.xml?key=##KEY##&OperatorRef=MTA&MonitoringRef=308209&LineRef=MTA NYCT_B63</span>
39 </a>{{/html}}
40
41
42
43 == SIRI StopMonitoring Responses ==
44
45 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>>Developers.SIRIMonitoredVehicleJourney]].
46
47 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##.
48
49 Other notes about the particularities of ##StopMonitoring## data is shown after the example response.
50
51 ##
52 <!~-~- SIRI container elements ~-~->
53 <Siri version="1.3" xmlns="http://www.siri.org.uk/siri">
54 <ServiceDelivery>
55 \\\\ <!~-~- The timestamp on the MTA Bus Time server at the time the request was fulfilled ~-~->
56 <ResponseTimestamp>2011-01-28T14:49:58-05:00</ResponseTimestamp>
57 \\\\ <!~-~- SIRI container for VehicleMonitoring response data ~-~->
58 <StopMonitoringDelivery version="1.3">
59 \\\\ <!~-~- Same as above. Required by the SIRI spec. ~-~->
60 <ResponseTimestamp>2011-01-28T14:49:58-05:00</ResponseTimestamp>
61 <!~-~- The time until which the response data is valid until. ~-~->
62 <ValidUntil>2011-01-28T14:50:58-05:00</ValidUntil>
63 \\\\ <!~-~- SIRI container for data about a particular vehicle service the selected stop ~-~->
64 <MonitoredStopVisit>
65 \\\\ <!~-~- The timestamp of the last real-time update from the particular vehicle ~-~->
66 <RecordedAtTime>2011-01-28T14:49:27-05:00</RecordedAtTime>
67 \\\\ <!~-~- A complete [[MonitoredVehicleJourney>>Developers.SIRIMonitoredVehicleJourney]] element. See the MonitoredVehicleJourney page for more information~-~->
68 <MonitoredVehicleJourney>...</MonitoredVehicleJourney>
69 \\\\ </MonitoredStopVisit>
70 \\\\ ... More MonitoredStopVisit elements
71 \\\\ </StopMonitoringDelivery>
72 </ServiceDelivery>
73 </Siri>
74 ##
75
76
77 === StopMonitoring Updates to Use Block-Level Assignment ===
78
79 ##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.
80
81 (% style="text-align:center" %)
82 [[image:wraparound.png]]
83
84 This is indicated by:
85
86 * 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.
87 * 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.
88 * The ##FramedJourneyRef## (which has the GTFS trip_id) being different for a given bus than in in the ##VehicleMonitoring## result for that bus.