Real-time arrival information for public transit vehicles is one of the key pieces of information provided by OneBusAway, but its 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.
Service alerts can encompass a lot of different scenarios, and while we eventually hope to support them all, were starting a specific use-case: adverse weather reroutes. Winter is rapidly approaching in the Pacific Northwest and the word on the street is that its going to be a big snow year. Snow and public transit generally make for a volatile mix, with local transit agencies having a difficult time communicating information about adverse weather reroutes and cancellations to riders where they need it most: waiting at a stop.
There are a number of issues beyond the scope of this document that we wont address here: the need for GPS vehicle tracking and a better radio network in KCM, or stream-lined rider communication within the agency.
Instead, well talk about extensions to the API to support service alert information and how those service alerts will be activated automatically.
We introduce a new <situation/> element. Its closely modeled on the PtSituation model from the SIRI Situation Exchange protocol (see http://www.kizoom.com/standards/siri/ for more details on the SIRI specification for exchanging real-time transit info). Lets 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:
The <affects/> element captures information about what transit entities are affected by a particular situation. Right now it supports two sub-elements:
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:
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.
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.
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>
Exposing service alerts in the !OneBusAway API is a good first step, but the service alerts are only as good as the data powering them. We are actively working with King County Metro and Pierce Transit on an automated system to active adverse reroutes automatically as they are activated in each agencys own customer information systems. More details on that as they become available.