Skip to content

Trip forcast

The journey forecast is an Open Service. The journey forecast is described in VDV 431 TripInfoRequest.

(trip forecast)

Technical description

To use the journey forecast a JourneyRef must be known. Unfortunately, this cannot be simply derived from the planned timetable (timetables available via the Timetable overview). The simplest way to generate the JourneyRef is from one of the other APIs (TripRequest or the arrival and departure display).

Key concepts

  • Stop: DiDok or stop datasets can also be referred to for this.
  • 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 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 (MT): 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”.

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

This request is transferred as body.

Explanatory notes on the elements in the request

Relevant elements in the request:

Name Mandat? Description Example
JourneyRef Yes(*) The JourneyRef must be generated or obtained from another source. odp:01012::H:j16:30441
OperatingDayRef No Day of operation. If no day of operation is specified, the current day of operation is used 2016-04-02T
Params No The request’s parameters See table below

(*) There is still a request about VehicleRef and TimeOfOperation in VDV 431. This should not be used as we do not run the VehicleRef.

Request’s Parameters:

Name Mandat? Description Example
UseTimetabledDataOnly No Determines whether information about days of operation is to be output in the result. Boolean. Default is false. false
IncludeCalls No Determines whether the stops in the journey are to be output in the result. Boolean. Default is true.

The set parameter is ignored. The system always uses true.

IncludePosition No Determines whether the current position of the means of transport is to be output in the result. Boolean. Default according to document would be true. But it is not implemented => Is not included.

The set parameter is ignored. The system always uses true.

IncludeService No Determines whether transport information about the journey is to be output in the result. Default is true.
Extension No No extensions are implemented.

Explanation of a response

The response has the following basic structure

The key elements of the response can be found in TripInfoResultStructure:

Name Mandat? Description Example
PreviousCall No/multiple Stops already travelled. Also includes the current stop if the journey is exactly at a stop. Own structure
CurrentPosition No Current position of the vehicle

Is not implemented.

Own structure
OnwardCall No/multiple The stops still ahead in the journey Own structure
Service No Traffic details Own structure described
OperatingDays No Days of operation for this route

Is not implemented.

OperatingDaysDescription No Machine-readable description of days of operation, e.g. “Monday to Friday” or “Sunday and public holidays”.

 

Is not implemented.

PreviousCall and OnwardCall have the following structure:

Name Mandat? Description Example
 StopPointRef  Yes  Reference to a code for a stop.  857000
 StopPointName  Yes Name of the stop for passenger information.

NB: Language is always DE.

<StopPointName>

<Text>Eiken</Text>

<Language>DE</Language>

</StopPointName>

 

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

<Text>43/44</Text>

<Language>DE</Language>

<PlannedBay>

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 last forecast. <EstimatedBay>

<Text>43</Text>

<Language>DE</Language>

</EstimatedBay>

 

 ServiceArrival  No  Arrival times ServiceArrival

<TimetabledTime>2016-04-02T11:56:00Z</TimetabledTime>

</ServiceArrival>

 

TimetabledTime Yes Timetabled arrival time

Always in Zulu time

 2016-04-02T11:20:00Z
RecordedAtTime No Actual arrival time

Is not used

EstimatedTime No Estimated arrival time

Only if real-time data is available

In the case of sections of the journey in the past, the last forecast or actual data applies.

 2016-04-02T11:20:00Z
 ServiceDeparture  No  Departure times  Content identical to ServiceArrival, apart from the fact that departure times are involved.
StopSequenceNumber Yes  Stop’s sequence number 4
DemandStop No Request stop The vehicle only services this stop based on advanced notification being given. Boolean Not available
UnplannedStop No Stop which was not provided for according to plan. Boolean NB: Is still being tested
NotServicedStop No The vehicle does not stop according to the plan Available (cancellations) NB: Example to be provided in due course
SituationFullRef No, multiple Reference to a failure message. This message can be found in the response’s ResponseContext or can be revealed in another way. Is not used

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:

screenshot-3

Comments

The following information is vital for external developers:

More detailed information

Start the discussion at disc.opentransportdata.swiss