Situation Element
Real-time arrival information for public transit vehicles is one of the key pieces of information provided by OneBusAway, but it’s only a part of the picture. Information about cancellations, detours, and explanations for why a transit vehicle is delayed are critical details for riders. While transit agencies have made some progress in publishing timely emails, SMS, and web notifications about service alert information, we think these approaches are generally too broad. We want to provide targeted service alerts through OneBusAway that tell you service alert information for just the transit services you are actively using.
API Representation
We introduce a new <situation/>
element. It’s closely modeled on the PtSituation model from the SIRI Situation Exchange schema. Let’s see an example:
<situation>
<id>1_1289972401385</id>
<creationTime>1289972401385</creationTime>
<environmentReason>heavySnowFall</environmentReason>
<summary>
<value>Snow Reroute</value>
</summary>
<description>
<value>Route diverted from Sandpoint Way and Princeton Ave to Campus Pkwy and University Way</value>
</description>
<affects>
<vehicleJourneys>
<vehicleJourney>
<lineId>1_30</lineId>
<direction>1</direction>
<calls>
<call>
<stopId>1_9980</stopId>
</call>
…
</vehicleJourney>
</vehicleJourneys>
</affects>
<consequences>
<consequence>
<condition>diversion</condition>
<conditionDetails>
<diversionPath>
<points>ue}aHt~hiVYxHt@lIxAjD|`@pb@tDbHh@|EHvEU~l@fAfN`C~E|DvDbIvB|NdClMxCbEbA`CxDfB`FLrKsNl]gA{@gPGKjF</points>
</diversionPath>
<diversionStopIds>
<string>1_9972</string>
<string>1_9974</string>
...
</diversionStopIds>
</conditionDetails>
</consequence>
</consequences>
</situation>
The <situation/>
element can be broken up into a couple of relevant sections:
Base Properties
id
- the unique id for this service alert situationcreationTime
- Unix timestamp of when this situation was created- reason for the service alert taken from TPEG codes - only one of these will be set
- `equipmentReason - ex. engineFailure
- `environmentReason - ex. heavySnowfall
- `personnelReason - ex. staffAbsence
miscellaneousReason
- ex. securityAlertsecurityAlert
- free text field
- descriptive text fields - each with a sub
<value/>
element, each also optionalsummary
- Short summarydescription
- Longer descriptionadvice
- Advice to the rider
Affects
The <affects/>
element captures information about what transit entities are affected by a particular situation. Right now it supports two sub-elements:
stops
- transit stopsvehicleJourneys
- transit vehicle journeys
The <stops/>
element has <stop>
sub-elements:
<stop>
<stopId>1_75403</stopId>
</stop>
The <vehicleJourneys/>
element has <vehicleJourney/>
sub-elements:
<vehicleJourney>
<lineId>1_30</lineId>
<direction>1</direction>
<calls>
<call>
<stopId>1_9980</stopId>
</call>
...
</calls>
</vehicleJourney>
The <vehicleJourney/>
element has the following properties:
lineId
- this is equivalent to a route iddirection
- an optional direction id specifying the direction of travelcalls
- optional elements specifying specific stops along the vehicle journey that are affected
Consequences
The <consquences/>
element captures a list of <consequence/>
elements that provide details about the consequences of the service alert. Right now, we mostly use this to share reroute information:
<consequences>
<consequence>
<condition>diversion</condition>
<conditionDetails>
<diversionPath>
<points>ue}aHt~hiVYxHt@lIxAjD|`@pb@tDbHh@|EHvEU~l@fAfN`C~E|DvDbIvB|NdClMxCbEbA`CxDfB`FLrKsNl]gA{@gPGKjF</points>
</diversionPath>
<diversionStopIds>
<string>1_9972</string>
<string>1_9974</string>
...
</diversionStopIds>
</conditionDetails>
</consequence>
</consequences>
Here we model an adverse weather reroute. The <consequence/>
element specifies a condition
of diversion
and the supplies optional condition details that indicates the path of the diversion and stop ids along the diverted path. This extended diversion information is optional.
Situations in API Methods
The <situation/>
element will appear in one place: under a <situations/>
element that is a new addition to the <references/>
element (see the main API reference). Since a situation can potentially be referenced multiple times in an API call, we felt putting situations in the references section was the best way to keep the response concise.
Situations will be referenced by id in API calls. For now, that primarily means the arrivals-and-departures-for-stop API call. Situations ids can appear in a number of places, depending on the context of a situation.
Stop-Specific Situations
If a situation affects a stop directly (as opposed to the routes serving that stop), it will appear directly under the <entry/>
element:
<entry class="stopWithArrivalsAndDepartures">
<stopId>1_75403</stopId>
<arrivalsAndDepartures>
<arrivalAndDeparture>...</arrivalAndDeparture>
...
</arrivalsAndDepartures>
<nearbyStopIds>
<string>1_75414</string>
</nearbyStopIds>
<situationIds>
<string>1_1289973261968</string>
</situationIds>
</entry>
Trip-Specific Situations
If a situation affects a specific trip or a call (an arrival/departure) at a stop by a specific trip, it will appear in the <situationIds/>
element of the <arrivalsAndDepartures/>
element.