Skip to content

Departure/arrival display (TRIAS 2020)

(TRIAS StopEventRequest)

The departure/arrival display is available as an Open Service (API). The departure/arrival display is described in VDV 431 – “StopEvent” service.

Technical description

One of the main applications using customer information is to create station boards/stop displays or display activities at a point or by a point (e.g. when arriving at a stop). Depending on the use case, information about arrivals and departures is of interest.

The departure/arrival display supplies the required data.

As main parameter, a stop must be chosen.

It should be noted that no metastations are used in this case. In other words, the following stops have be used, for instance, for the Point of Interest Bern, Wankdorf:

  • 8516161, Bern Wankdorf
  • 8590129, Bern Wankdorf, Bahnhof
  • 8595543, Bern Wankdorf, Bahnhof Nord

Key concepts

  • Stops: Use DiDok or stop datasets from other sources.
  • Journeys: A journey involves transporting customers along a particular route, according to a particular timetable connection, by a particular means of transport, at a particular time, in a particular direction.
  • Timetable: A timetable determines the progress of a means of transport in public short- and long-distance passenger traffic and in railway freight traffic. The information required for this includes train numbers, days of operation, routes, arrival, departure and passing times at the stops, as well as permissible speeds in individual sections of the route.
  • Forecasts: Forecasts concern a train’s running times in the future, which are calculated based on the train’s current location. This also takes into account conflicts and their currently intended settlements in the next x minutes. A less elaborate method is used to calculate future values of the forecast.
  • Means of transport (VM): Either used synonymously with vehicles (train, boat, tram, bus) from different carriers or in the sense of a “transport system” (public transport etc.).
  • DateTime in Response: It is always based on Zulu time (i.e. UTC). That means, you have to add two hours in summer and one hour in winter.

Technical aspects

API Explorer

Authorisation and Open Services

An API keyword is required to access this API. It can be obtained via the Developer Portal. The token must also be sent in the HTTP header as “Authorization”.

Access URL

API: https://api.opentransportdata.swiss/trias2020

Test-Key: 57c5dbbbf1fe4d000100001842c323fa9ff44fbba0b9b925f0c052d1

With the Authorization header and Content type= “text/XML” or “application/XML”

Authorization header

 

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<Trias version="1.1" xmlns="http://www.vdv.de/trias" xmlns:siri="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ServiceRequest>
        <siri:RequestTimestamp>2020-09-29T12:44:46.206Z</siri:RequestTimestamp>
        <siri:RequestorRef>API-Explorer</siri:RequestorRef>
        <RequestPayload>
            <StopEventRequest>
                <Location>
                    <LocationRef>
                        <StopPointRef>8502113</StopPointRef>
                    </LocationRef>
                    <DepArrTime>2020-11-04T14:04:11</DepArrTime>
                </Location>
                <Params>
                    <NumberOfResults>5</NumberOfResults>
                    <StopEventType>departure</StopEventType>
                    <IncludePreviousCalls>true</IncludePreviousCalls>
                    <IncludeOnwardCalls>true</IncludeOnwardCalls>
                    <IncludeRealtimeData>true</IncludeRealtimeData>
                </Params>
            </StopEventRequest>
        </RequestPayload>
    </ServiceRequest>
</Trias>

This request is transferred as body.

Explanatory notes on the elements in the request

The request has two key elements:

Name Mandatory? Description Example
StopPointRef Yes(*) A stop code from DiDok or the stop list  8507000
DepArrTime No Contains the arrival and departure time (see also the StopEventType parameter). Requests can only be made -1 to +24 hours. If the element is missing, the current time applies. Zulu time is not required in this case.

The seconds must be specified.

 2020-06-27T13:34:00
Params No The request’s parameters See table below

Params – the other parameters are:

Name Mandatory? Description Example
NumberOfResults No Default 40, Maximum 40 20
StopEventType Yes There are two valid values: departure/ arrival. departure
IncludePreviousCalls No The stops before the requested stop should be included: true/false

Default true

false
IncludeOnwardCalls No The stop after the requested stop should be included: true/false

Default true

false
IncludeRealtimeData No Real-time data should also be transferred: true/false

Default false

false

Explaining a response

The response has the following basic structure:

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<trias:Trias xmlns:siri="http://www.siri.org.uk/siri" xmlns:trias="http://www.vdv.de/trias" xmlns:acsb="http://www.ifopt.org.uk/acsb" xmlns:ifopt="http://www.ifopt.org.uk/ifopt" xmlns:datex2="http://datex2.eu/schema/1_0/1_0" version="1.1">
    <trias:ServiceDelivery>
        <siri:ResponseTimestamp>2020-09-29T12:44:56Z</siri:ResponseTimestamp> 
        <siri:ProducerRef>EFAController10.4.6.43-OJP-EFA01-P</siri:ProducerRef> 
        <siri:Status>true</siri:Status> 
        <trias:Language>de</trias:Language> 
        <trias:CalcTime>43</trias:CalcTime> 
        <trias:DeliveryPayload> 
            <trias:StopEventResponse> 
                <trias:StopEventResponseContext> 
                    <trias:Situations></trias:Situations> 
                </trias:StopEventResponseContext> 
                <trias:StopEventResult> 
                    <trias:ResultId>ID-236A5F60-0E9E-409F-9C66-5BE8BF72356D</trias:ResultId>
                    <trias:StopEvent>
                        <!-- ... -->
                    </trias:StopEvent>
                </trias:StopEventResult>
            </trias:StopEventResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

A “StopEvent” contains the following elements:

  • PreviousCall: stops before the current stop
  • ThisCall: current stop
  • OnwardCall: next stop
  • Service: information about the journey

The request always returns the complete journey from the first to the last stop.

 

New in TRIAS2020:

The response returns the following new elements:

  • “CalcTime” (computer time required to answer the request [ms])
  • “StopEventResponseContext” with “Situations” (SIRI model of events or disturbances)
  • “EstimatedTime” was previously only supplied for “ThisCall”, now also for “PreviousCall” and “OnwardCall”

“MoreData” has been obsoleted, the response returns all the data available.

 

PreviousCall / This Call / OnwardCall

PreviousCall:

<trias:PreviousCall>
    <trias:CallAtStop>
        <trias:StopPointRef>8504106</trias:StopPointRef>
        <trias:StopPointName>
            <trias:Text>Bern Bümpliz Süd</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:StopPointName>
        <trias:PlannedBay>
            <trias:Text>1</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:PlannedBay>
        <trias:ServiceArrival>
            <trias:TimetabledTime>2020-09-29T15:32:00Z</trias:TimetabledTime>
            <trias:EstimatedTime>2020-09-29T15:32:00Z</trias:EstimatedTime>
        </trias:ServiceArrival>
        <trias:ServiceDeparture>
            <trias:TimetabledTime>2020-09-29T15:32:00Z</trias:TimetabledTime>
            <trias:EstimatedTime>2020-09-29T15:32:00Z</trias:EstimatedTime>
        </trias:ServiceDeparture>
        <trias:StopSeqNumber>6</trias:StopSeqNumber>
    </trias:CallAtStop>
</trias:PreviousCall>

ThisCall

<trias:ThisCall>
    <trias:CallAtStop>
        <trias:StopPointRef>8507000</trias:StopPointRef>
        <trias:StopPointName>
            <trias:Text>Bern</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:StopPointName>
        <trias:PlannedBay>
            <trias:Text>2</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:PlannedBay>
        <trias:ServiceDeparture>
            <trias:TimetabledTime>2020-09-29T15:42:00Z</trias:TimetabledTime>
            <trias:EstimatedTime>2020-09-29T15:42:00Z</trias:EstimatedTime>
        </trias:ServiceDeparture>
        <trias:StopSeqNumber>8</trias:StopSeqNumber>
    </trias:CallAtStop>
</trias:ThisCall>

OnwardCall:

<trias:OnwardCall>
    <trias:CallAtStop>
        <trias:StopPointRef>8516161</trias:StopPointRef>
        <trias:StopPointName>
            <trias:Text>Bern Wankdorf</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:StopPointName>
        <trias:PlannedBay>
            <trias:Text>1</trias:Text>
            <trias:Language>de</trias:Language>
        </trias:PlannedBay>
        <trias:ServiceArrival>
            <trias:TimetabledTime>2020-09-29T15:45:00Z</trias:TimetabledTime>
            <trias:EstimatedTime>2020-09-29T15:45:00Z</trias:EstimatedTime>
        </trias:ServiceArrival>
        <trias:ServiceDeparture>
            <trias:TimetabledTime>2020-09-29T15:45:00Z</trias:TimetabledTime>
            <trias:EstimatedTime>2020-09-29T15:45:00Z</trias:EstimatedTime>
        </trias:ServiceDeparture>
        <trias:StopSeqNumber>9</trias:StopSeqNumber>
    </trias:CallAtStop>
</trias:OnwardCall>
Name Mandatory? Description Example
StopPointRef Yes A stop code
TimetabledTime Yes  This is the time according to the scheduled timetable. NB: Zulu time. 2020-08-18T02:54:00Z
Estimatedtime No Time based on forecast. NB: “Estimatedtime” is only available for journeys which have real-time data and only for “ThisCall”. “Estimatedtime” can be the same as “TimetabledTime”, if no deviation is expected.

In the case of sections of the journey (“PreviousCall”) in the past, the last forecast or actual data applies.

 2020-08-18T02:54:40Z
PlannedBay No Contains the planned platform according to the timetable.
EstimatedBay No Contains the forecast platform.  12A
StopSequenceNumber Yes All stops are numbered consecutively. 3

Service

The “Service” structure is described here: Service (VDV 431)

Errors/Problems

The response will contain an “ErrorMessage” if there were problems executing the request:

<? xml version="1.0" encoding="UTF-8"?>
<trias:Trias xmlns:siri="http://www.siri.org.uk/siri" xmlns:trias="http://www.vdv.de/trias" xmlns:acsb="http://www.ifopt.org.uk/acsb" xmlns:ifopt="http://www.ifopt.org.uk/ifopt" xmlns:datex2="http://datex2.eu/schema/1_0/1_0" version="1.1">
    <trias:ServiceDelivery>
        <siri:ResponseTimestamp>2020-09-29T19:55:24Z</siri:ResponseTimestamp>
        <siri:ProducerRef>EFAController10.4.6.43-OJP-EFA02-P</siri:ProducerRef>
        <siri:Status>true</siri:Status>
        <trias:Language>de</trias:Language>
        <trias:CalcTime>16</trias:CalcTime>
        <trias:DeliveryPayload>
            <trias:StopEventResponse>
                <trias:ErrorMessage>
                    <trias:Code>-4030</trias:Code>
                    <trias:Text>
                        <trias:Text>STOPEVENT_NOEVENTFOUND</trias:Text>
                        <trias:Language>de</trias:Language>
                    </trias:Text>
                </trias:ErrorMessage>
                <trias:StopEventResponseContext>
                    <trias:Situations></trias:Situations>
                </trias:StopEventResponseContext>
            </trias:StopEventResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

 

Comments

IMPORTANT: External developers should be aware of the following points:

  • Stops have to be submitted in the form of a DiDok number. This means that the DiDok or station file needs to be parsed and processed. The DiDok number can be obtained from a search according to name or geographic coordinates.
  • Any metastops are ignored.
  • The time of arrival or departure can be provided.
  • Requests based on specific stop sections (like platform, post, kerb) are not possible.

Special case Postauto AG

The timetable data for Postauto AG (PAG) is supplied by business organisation 801, i.e., Postauto Switzerland. It contains lines which, although they are different (from different regions and carriers), have the same line numbers. This includes a couple of stops (DiDok numbers) which are called at by two intersecting lines. This situation means that in the TRIAS interfaces (VDV431), all the destination texts are mixed up in the “DestinationText” data field. This, in turn, results in a false output. As restructuring is being carried out with the implementation of KUBUS (official railway timetable) and the import of HRDF data into the Open Data system, it does not make sense at the moment (economically) to make an extensive adjustment to the import process (using the unique line ID from PAG in the *I RN line = PlanBox line number, previously PLADIS number).

Solution

When importing the HRDF data, the “train number instead of journey key” flag is disabled in DIVA on the relevant line. This changes the JourneyRef (journey number) on the TRIAS interfaces (GTFS is not affected). The data fields used to represent the line (LineRef or PublishedLineName) are not affected by this and are output as before.

Further information