Add documentation for URL field, publicationWindows in service alerts (situation elements)

barbeau commented 7 years ago

There is an undocumented url and publicationWindows fields in situation elements. For example, see http://buseta.wmata.com/onebusaway-api-webapp/api/where/arrivals-and-departures-for-stop/1_18090.json?minutesAfter=65&app_ver=71&key=v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc%3DcGF1bGN3YXR0c0BnbWFpbC5jb20%3D.

situations: [
{
activeWindows: [ ],
allAffects: [],
consequences: [
{
condition: "significant_delays",
conditionDetails: null
}
],
creationTime: 1472224980000,
description: {
lang: "en",
value: "Impacts of SafeTrack Surge #9 on Metrobus Customers"
},
id: "1_261B7F0A8A68F37591996B11D5C5CED3",
publicationWindows: [ ],
reason: "UNKNOWN_CAUSE",
severity: "unknown",
summary: {
lang: "en",
value: "Impacts of SafeTrack Surge #9 on Metrobus Customers"
},
url: null // <-- This will include a URL with more details, if the agency populates that field
},

These fields aren't reflected in the current REST API docs: http://developer.onebusaway.org/modules/onebusaway-application-modules/current/api/where/elements/situation.html

We should add documentation for these field (and describe how publicationWindows is different from activeWindows).

cc @sheldonabrown

barbeau commented 7 years ago

Here's the populated URL field:

...
summary: {
lang: "en",
value: "Impacts of SafeTrack Surge #9 on Metrobus Customers"
},
url: {
lang: "en",
value: "http://www.wmata.com/rider_tools/metro_service_status/advisories.cfm?AID=5749"
}

barbeau commented 3 years ago

Here is how OBA Android interprets url field:

A URL to a human-readable website with more details on the alert

This is in-line with the GTFS Realtime Alert.url definition at https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-alert which is:

The URL which provides additional information about the alert.

OBA Android doesn't use publicationWindows so I'm not sure how that should be used and how it differs from activeWindows.

OneBusAway / onebusaway-application-modules

Add documentation for URL field, publicationWindows in service alerts (situation elements) #187