Skip to content

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. A starting stop and a destination point are expected to provide the input. Departure and arrival times can also be specified.

The implementation used by SBB enables it only to search for direct journeys. For example:

  • Bern – Olten findet eine Antwort,_ da es direkte Fahrten gibt.
  • Lausanne – Chur findet keine,  da man immer mind. 1 mal umsteigen muss.

    Key concepts

    • Stops: In this case, DiDok or Stop datasets can also be referred to.
    • 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.
    • Forecast: Forecasts concern a train’s running times in the future, which are calculated from 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 the further progress 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: This is always based on Zulu time (i.e. UTC). It means adding 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”.

URL für den Aufruf

Access URL

HTTP POST at https://api.opentransportdata.swiss/trias

(NB: No “/” at the end)

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

Authorization header

Sample request

In the case of the current TripRequest service, the developer can request a starting and destination stop (DiDok ID) and, optionally, the relevant real-time data for a time in the future (default = now). They will receive real-time information, if available.

This request is transferred as body.

Explanatory notes on the elements in the request

The Request features the following key elements:

Name Mandat? Description Example
Origin  Yes Location data for the 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. 2016-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  

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

The following VDV 431 parameters are not implemented either:

  • 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.

Extracting and explaining a response

The response has the following basic structure:

The response includes the following elements

  • TripResponse: Trip itself
  • It contains individual TripResults.

“MoreData” is always false, as all the data is supplied.

Response: Trip

Name Mandat? 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 2016-08-01T07:19:00Z
endTime  Yes  Trip’s end time in Zulu time 2016-08-01T07:26:00Z
Interchanges  Yes  Number of changes 0

Response TripLeg

Name Mandat? 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 used, TimedLegs are always used.
LegBoard Yes Leg’s start location
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 2016-08-01T07:19:00Z
EstimatedTime No Forecast departure time In the case of sections of the journey in the past, the last forecast or actual data applies. 2016-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 plan status. <EstimatedBay>

<Text>43</Text>

<Language>DE</Language>

</EstimatedBay>

PlannedBay 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. <PlannedBay>

<Text>43/44</Text>

<Language>DE</Language>

</PlannedBay>

StopSequenceNumber Yes Stop’s sequence number 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) process.

Service

The “Service” structure is described here:

Errors/Problems

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

screenshot-3

Comments

The following information is vital for external developers:

  • EstimatedBay and PlannedBay contain platform information as supplied via the systems. In other words, Platform “12” and Platform “12A” are considered two separate platforms. In Zürich HB it is as planned, e.g. “41/42”. In PlannedBay it can only be “41”.
  • Only direct trains can be shown due to restrictions.
  • Metastops are also ignored. In other words, a result for Wankdorf to Bern is found. But not for Wankdorf, Bahnhof to Bern.
  • Failed journeys (unlike in StopEvent) are not indicated or marked.

More detailed information