Skip to content
LoginRegister
DEENFRIT
Home
Open data platform mobility Switzerland
  2. Cookbook
  3. TripRequest (TRIAS 2020)

TripRequest (TRIAS 2020)

(TRIAS TripRequest)

TripRequest is an Open Service. TripRequest is a special form of journey forecast and is described in VDV 431 TripRequest.

It is important to understand that this platform implements only a subset of the TripRequest options. The documentation below describes TripRequest and how it is implemented by SBB.

Technical description

TripRequest is a route planner. Required inputs are a start and a destination stop. Departure and arrival times can also be specified.

The implementation by SBB allows for direct connections only. For example:

  • Bern – Olten: this search yields a result since there are direct trains between the two stops.
  • Lausanne – Chur: this search yields no result because there is no connection without changing trains at least once.

    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-30T11:42:03.007Z</siri:RequestTimestamp>
        <siri:RequestorRef>API-Explorer</siri:RequestorRef>
        <RequestPayload>
            <TripRequest>
                <Origin>
                    <LocationRef>
                        <StopPointRef>8500320</StopPointRef>
                    </LocationRef>
                    <DepArrTime>2020-09-30T01:02:03</DepArrTime>
                </Origin>
                <Destination>
                    <LocationRef>
                        <StopPointRef>8500322</StopPointRef>
                    </LocationRef>
                </Destination>
                <Params>
                    <NumberOfResults>1</NumberOfResults>
                    <IncludeTrackSections>true</IncludeTrackSections>
                    <IncludeLegProjection>true</IncludeLegProjection>
                    <IncludeIntermediateStops>true</IncludeIntermediateStops>
                </Params>
            </TripRequest>
        </RequestPayload>
    </ServiceRequest>
</Trias>

The request is transferred as body.

Explanatory notes on the elements in the request

The Request contains the following key elements:

Name Mandat? Beschreibung Beispiel
Origin Yes Departure location 
<Origin>
    <LocationRef>
        <StopPointRef>8500320</StopPointRef>
    </LocationRef>
    <DepArrTime>2016-08-01T09:11:40</DepArrTime>
</Origin>

 
LocationRef Yes –
StopPointRef  Yes  Stop as a Didok code. 8500320
DepArrTime  No Departure or arrival time. If no time is specified, the current time is used. 2020-08-01T09:11:40
Via  No, multiple One or more “via” locations. The specified “via” locations must be reached in the pre-defined sequence. The server can replace a “via” stop with an equivalent stop

NB: Should not be used

 –
NoChangeAt  No, multiple  Specifies stops at which no change can be made.

NB: Is not used

 –
Destination  Yes Location data for the destination location

Has the same structure as Origin

 –
Params  No … see table below –

Structure of Params:

Name Mandat? Description Example
IncludeTrackSections  No The TrackSections are indicated. Default = true.

Implemented, but always just one track, so it is not of particular interest.

 true
IncludeLegProjection  No This parameter is not implemented. true
IncludeIntermediateStops  No Implemented, but no intermediate stops indicated. true
NumberOfResults No Minimum number of connection messages which the user expects. Default = 3 and the figure given is always at least 3, even if the value is actually lower. 20

Many of the following VDV 431 parameters are not implemented either (this list does not yet reflect the improvements brought by TRIAS2020 – TODO):

  • PtModeFilter: Filter based on types of forms of transport
  • LineFilter: Permitted lines (refined for directions, if appropriate)
  • OperatorFilter: Filter based on transport companies
  • NoSingleStep: Determines whether the user can cope with a step. If not, this parameter is set to “true”.
  • NoStairs: Determines whether the user can cope with stairs. If not, this parameter is set.
  • NoEscalator: Determines whether the user can use an escalator. If not, this parameter is set.
  • NoElevator: Determines whether the user can use an elevator.  If not, this parameter is set.
  • NoRamp: Determines whether the user can cope with a ramp If not, this parameter is set.
  • LevelEntrance: Determines whether users require level access when boarding and alighting from vehicles. In some cases, a lifting device on the vehicle or on the platform is also sufficient. If level access is required, this parameter is set.
  • BikeTransport: Determines whether the user wants to take a bicycle on board the means of transport. If yes, this parameter is set.
  • WalkSpeed: Change to the standard walk speed as a percentage The default value is 100. Values lower than 100 indicate a slower speed, while values greater than 100 indicate a faster speed.
  • IgnoreRealtime Data: If this parameter is set, no real-time data or fault information should be considered in the connection search, apart from only target timetable data.
  • ImmediateTripStart: If this parameter is set, the connection being searched for should start immediately at the specified start point. It will then not be necessary to improve the departure time, according to the rule “Start as late as possible, as long as only the same arrival time is guaranteed at the destination”.
  • InterchangeLimit: Maximum number of interchanges allowed. NB: This parameter is ignored.
  • AlgorithmType: Type of target function, based on which the algorithm should improve the connection: fastest, minChanges, leastWalking, leastCost
  • ItModesToCover: For each type of intermodal connection in this list, a separate monomodal connection should be found, in addition to the intermodal connections.
  • IncludeTurnDescription: Determines whether route information should be output in the result with recommendations for detours. Default is false. The parameter is ignored.
  • IncludeAccessibilitiy: Determines whether information about accessibility should be output in the result. Default is false. The parameter is ignored.
  • IncludeFares: Determines whether fare information should be output in the result. Default is false. The parameter is ignored.
  • IncludeOperatingDays: Determines whether information about days of operation should be output in the result. Default is false.
  • FaresParam: Parameter for providing fares. The parameter is ignored.
  • Extension Extensions. Not implemented.

Explaining a response

The response has the following basic structure:

<? 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-30T11:25:56Z</siri:ResponseTimestamp>
        <siri:ProducerRef>EFAController10.4.10.25-OJP-EFA01-P</siri:ProducerRef>
        <siri:Status>true</siri:Status>
        <trias:Language>de</trias:Language>
        <trias:CalcTime>72</trias:CalcTime>
        <trias:DeliveryPayload>
            <trias:TripResponse>
                <trias:TripResponseContext>
                    <trias:Situations></trias:Situations>
                </trias:TripResponseContext>
                <trias:TripResult>
                    <trias:ResultId>ID-2BE4715E-B8EA-4550-940F-471B34CA2D60</trias:ResultId>
                    <trias:Trip>
                        <trias:TripId>ID-6A87028D-B0B9-4302-B7B8-7483FC31A0F4</trias:TripId>
                        <trias:Duration>PT15M</trias:Duration>
                        <trias:StartTime>2020-09-30T10:20:00Z</trias:StartTime>
                        <trias:EndTime>2020-09-30T10:35:00Z</trias:EndTime>
                        <trias:Interchanges>0</trias:Interchanges>
                        <trias:Distance>10724</trias:Distance>
                        <trias:TripLeg>
                            <trias:LegId>1</trias:LegId>
                            <trias:TimedLeg>
                                <trias:LegBoard>
                                    <trias:StopPointRef>8572748</trias:StopPointRef>
                                    <trias:StopPointName>
                                        <trias:Text>Stein-Säckingen, Bahnhof</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:StopPointName>
                                    <trias:PlannedBay>
                                        <trias:Text>C</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:PlannedBay>
                                    <trias:ServiceDeparture>
                                        <trias:TimetabledTime>2020-09-30T10:20:00Z</trias:TimetabledTime>
                                    </trias:ServiceDeparture>
                                    <trias:StopSeqNumber>1</trias:StopSeqNumber>
                                </trias:LegBoard>
                                <!-- weitere Legs -->
                                <trias:Service>
                                    <trias:OperatingDayRef>2020-09-30</trias:OperatingDayRef>
                                    <trias:JourneyRef>ojp:92033:Y:R:j20:41:37243</trias:JourneyRef>
                                    <trias:LineRef>ojp:92033:Y:R</trias:LineRef>
                                    <trias:DirectionRef>return</trias:DirectionRef>
                                    <trias:Mode>
                                        <trias:PtMode>bus</trias:PtMode>
                                        <trias:BusSubmode>localBus</trias:BusSubmode>
                                        <trias:Name>
                                            <trias:Text>Bus</trias:Text>
                                            <trias:Language>de</trias:Language>
                                        </trias:Name>
                                    </trias:Mode>
                                    <trias:PublishedLineName>
                                        <trias:Text></trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:PublishedLineName>
                                    <trias:OperatorRef>ojp:7000</trias:OperatorRef>
                                    <trias:Attribute>
                                        <trias:Text>
                                            <trias:Text>VELOS: Keine Beförderung möglich</trias:Text>
                                            <trias:Language>de</trias:Language>
                                        </trias:Text>
                                        <trias:Code>A__VN</trias:Code>
                                    </trias:Attribute>
                                    <!-- weitere Attributes -->
                                    <trias:OriginText>
                                        <trias:Text></trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:OriginText>
                                    <trias:DestinationText>
                                        <trias:Text>Laufenburg, Bahnhof</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:DestinationText>
                                </trias:Service>
                            </trias:TimedLeg>
                        </trias:TripLeg>
                    </trias:Trip>
                </trias:TripResult>
            </trias:TripResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

The response includes the following elements

  • TripResponse: the response
  • It contains individual TripResults.

Trip

Name Mandatory Description Example
ResultID Yes ID for internal purposes  ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
TripID Yes ID for internal purposes  ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
Duration Yes Total duration in minutes 7
startTime  Yes  Trip’s start time in Zulu time 2020-08-01T07:19:00Z
endTime  Yes  Trip’s end time in Zulu time 2020-08-01T07:26:00Z
Interchanges  Yes  Number of changes 0

TripLeg

Name Mandatory Description Example
LegID Yes Serial number of leg

Always 1 in the implementation used by SBB

 1
TimedLeg Yes VDV 431 uses different types of legs. In the current implementation only TimedLegs are used. –
LegBoard Yes Start location of the leg –
StopPointRef Yes Didok code 8500320
StopPointName Yes Name of Didok code. NB: Language is always DE. –
ServiceDeparture Yes Departure time structure –
TimetabledTime Yes Timetabled departure time 2020–08–01T07:19:00Z
EstimatedTime No Forecast of departure time If the corresponding section of the journey in the past, the last forecast or actual data applies. 2020–08–01T07:19:00Z
EstimatedBay No Name of the platform/stop where passengers must board or alight from the vehicle (when used along with specific route information; if a general name is specified in StopPointName, it is similar to the stop name). According to the current planning status. 
<trias:EstimatedBay>
  <trias:Text>43</trias:Text>
  <trias:Language>DE</trias:Language>
</trias:EstimatedBay>
Planned Bay No Name of the platform/stop where passengers must board or alight from the vehicle (when used along with specific route information; if a general name is specified in StopPointName, it is similar to the stop name). According to last forecast. 
<trias:PlannedBay>
  <trias:Text>43/44</trias:Text>
  <trias:Language>DE</trias:Language>
</trias:PlannedBay>
StopSequenceNumber Yes Sequence number of the stop 1
LegIntermediate No Same structure as LegBoard for an intermediate stop. Contains both ServiceDeparture and ServiceArrival as times. –
LegAlight Yes Same structure as LegBoard for an end stop. Contains only ServiceArrival as time. –
Service Yes Service details for this leg –
LegTrack No Detailed (geometric) route. –

Service

The “Service” structure is described here:

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-30T13:36:50Z</siri:ResponseTimestamp>
        <siri:ProducerRef>EFAController10.4.10.25-OJP-EFA02-P</siri:ProducerRef>
        <siri:Status>true</siri:Status>
        <trias:Language>de</trias:Language>
        <trias:CalcTime>20</trias:CalcTime>
        <trias:DeliveryPayload>
            <trias:TripResponse>
                <trias:ErrorMessage>
                    <trias:Code>-4000</trias:Code>
                    <trias:Text>
                        <trias:Text>TRIP_NOTRIPFOUND</trias:Text>
                        <trias:Language>de</trias:Language>
                    </trias:Text>
                </trias:ErrorMessage>
            </trias:TripResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

Comments

IMPORTANT: External developers need to be aware of the following:

  • EstimatedBay and PlannedBay contain platform information as supplied by the systems. In other words, Platform “12” and Platform “12A” are considered two separate platforms. It is possible that a forecast for Zürich HB says “41/42”, while PlannedBay will be “41”.
  • Only direct trains will be shown.
  • Metastops are ignored. That means, a result is found for a query from Wankdorf to Bern – but none will be found for Wankdorf, Bahnhof to Bern.
  • Cancelled trips are not indicated or marked (unlike as in StopEvent

Further information