Back to API parent page

The <situation/> Element

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.

API Representation

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:

Base Properties

  • id - the unique id for this service alert situation
  • creationTime - 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. securityAlert
    • securityAlert - free text field
  • descriptive text fields - each with a sub <value/> element, each also optional
    • summary - Short summary
    • description - Longer description
    • advice - 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 stops
  • vehicleJournerys - 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 id (I have good reasons for not calling it routeId that Im happy to discuss offline)
  • direction - an optional direction id specifying the direction of travel
  • calls - 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 V2 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.

Automating Service Alerts

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.