Deviations

The application Ukur detects and enables subscriptions for deviations in traffic based on real-time information from the application Anshar.

BASE_URL: https://api.entur.io/realtime-deviations/v1/subscription

Subscriptions

There are two ways to create and maintain subscriptions in Ukur: an original JSON way and the standardized SIRI format with XML. The latter does not support subscriptions on to- and from-stops, but otherwise they are quite similar. Ukur is not intended to push messages directly to end-user clients, instead it is expected that the subscriber handles that with knowledge about what to push, how often etc. Also the subscriber should make sure that similar subscriptions to end-users result in only one subscription to Ukur.

Proprietary JSON format

To subscribe, post subscription data to https://{BASE_URL}/subscription as application/json.

The subscription must contain a logical name, a public reachable push address and what is subscribed upon: from and to stops and/or lines and/or codespaces.

Parameter name	Default value	Valid values	Description
name	N/A	string	A logical name to describe the subscription.
pushAddress	N/A	URL	The address to which deviation messages for this subscription should be sent.
type	`"ALL"`	`"ALL"`, `"ET"`, `"SX"`	The source of deviation messages you are interested in.
fromStopPoints	N/A	List of strings	A list of StopPoints to filter deviations from.
toStopPoints	N/A	List of strings	A list of StopPoints to filter deviations to.
lineRefs	N/A	List of strings	A list of lineRefs to filter on.
codeSpaces	N/A	List of strings	A list of codeSpaces to filter on.
useSiriSubscriptionModel	`false`	boolean	Whether notifications should be wrapped in a Siri root or not.
initialTerminationTime	`null` (meaning never)	ISO8601 Timestamp	An ISO8601 timestamp string for when the subscription should be deleted.
heartbeatInterval	`null` (meaning never)	ISO8601 Duration	Period for heartbeats according to the Duration format from the W3C XML Schema 1.0 at which heartbeats (empty Siri/HeartbeatNotification xml messages) should be sent to the push address, default is null (no heartbeats). The interval is handled approximately, and notifications can come several seconds later than what is specified (depending of how often we configure Ukur to handle heartbeats)...
pushAllData	`false`	boolean	Can be set to true if all realtime messages matching the subscription should be pushed, and not just those with deviations.
minimumDelay	`"PT15M"`	ISO8601 Duration	The minimum delay required for sending a message.
deviationType	`"DELAYED"`	`"DELAYED"`, `"TRACK_CHANGE"`, `"CANCELED"`	The type of deviation messages you are interested in.

Example

{
    "name": "Test subscription",
    "pushAddress": "https://myserver/push",
    "type": "ALL",
    "fromStopPoints": ["NSR:Quay:551", "NSR:Quay:553", "NSR:Quay:550"],
    "toStopPoints": ["NSR:Quay:695", "NSR:Quay:696"],
    "lineRefs": ["NSB:Line:L14", "NSB:Line:R11"],
    "codespaces": ["NSB", "RUT"],
    "useSiriSubscriptionModel": false,
    "initialTerminationTime": "9999-01-01T00:00:00+01:00",
    "heartbeatInterval": "PT15M",
    "pushAllData": false,
    "minimumDelay": "PT15M",
    "deviationType": "DELAYED"
}

After successful creation of the new subscription, Ukur responds with the same object with the ID-attribute set. This ID can be used to remove the subscription by issuing a http delete to https://{BASE_URL}/subscription/{subscriptionId}. Update is supported: Just post a subscription with the proper ID and desired new state to https://{BASE_URL}/subscription/.

StopPoints are fully qualified national IDs on stop places and quays. Use Stoppestedsregisteret to look them up. The SIRI messages received from Anshar uses both stop places and quays to identify affected stops, Ukur maps stop places to quays so the subscription does not have to specify quays unless only certain quays are interesting. Stops not following the national ID format are ignored (as they never will be referenced). Also both from and to StopPoints must be present to receive push messages.

Continue reading on https://github.com/entur/ukur/blob/master/functional_description.md

Source code Github

https://github.com/entur/ukur

Authentication

This API is open under NLOD licence, however, it is required that all consumers identify themselves by using the header ET-Client-Name. Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: "company-application"

Header examples:

"brakar-journeyplanner"
"fosen_utvikling-departureboard"
"nor_way_bussekspress-nwy-app"