Table of contents

Search on the page

Train Formation Service (Train Composition)

#AutoTranslate

Brief Description

Formation data is information about the wagons (and locomotives) of a train, including the composition of a train. Formation data includes not only the position of individual wagons on a train, but also the characteristics of individual wagons.

Since autumn 2024, we have been offering a REST API that provides the formation data for a train for a specific train number on a specific day of operation as a JSON data structure.

For example, our formation data can help you find out which coach on a specific train (with a specific train number) has low-floor access, i.e. easy access for wheelchairs or pushchairs.

With the ‘Train Formation Visualization‘, we also provide a visualisation for displaying the API data for a train, see the screenshot below. To do this, the train number must first be determined from an online timetable, e.g. from https://www.bls.ch.

https://opentdatach.github.io/train-formation-view

Access the API

Please note:

Note: A description of how to access the APIs can be found here: Howto: Accessing our APIs with API Keys.

Functional Description

Who is behind it?

This service is provided by the Customer Information Plus System Tasks (SKI+) team on behalf of the Federal Office of Transport (FOT) in Switzerland.

We obtain the formation data from these two systems:

  1. The Training Service (FOS) SBB, with which various railway undertakings (EVU) their formation data. The list of permissible EVU is limited to those who have consented to the use of their formation data.
  2. The means of transport interface of the real-time system (CUS) of the customer information system tasks (SKI). CUS manages the real-time data on all modes of public transport in Switzerland.

While the FOS interface only provides the details of the formation, the CUS interface adds further details to the data, specifically the position of the wagons (sectors) on the track at the stops.

Why does opentransportdata.swiss offer this?

Data on the formation of a train can be used to provide users with information:

  • the section of a platform at a station wheelchair-accessible boarding is possible, which is particularly important in light of the Disability Discrimination Act (DDA),
  • in which coaches bike hooks are available,
  • how many seats are generally available in a coach,
  • in combination with our Occupancy forecast the expected occupancy of the train can even be displayed,
  • which locomotive and wagon types operate on which routes, for train spotters or for transport companies that combine their services with other railways.

Technical Description

What services (interface endpoints) does our Train Formation Service offer?

Our Train Formation Service supports the following three request variants. The details of the requests are also documented via the OpenAPI interface:

  1. Stop-based – https://api.opentransportdata.swiss/formation/v2/formations_stop_based:
    • This service returns the formations for each individual stop on a train’s journey.
    • Parameters:
      • The name of a EVU.
      • An operating day: The day for which the formation is to be queried. The date cannot be in the past. Please note: Date can only be from today (due to inclusion of real-time data from CUS).
      • The train number, also known as the means of transport: The train for which you would like to request the formation. This number can be obtained in various ways, including via our timetable data in different data formats.
    • Return values: a JSON data structure with:
      • the stops of a train, with the stop details, the formation with which the train departs from the stops, when, from which track, and with which locomotives/coaches it remains together. The key here is to specify the formation in a compact format that originates in CUS.
      • This search does not contain all the details of every wagon.
      • The interpretation of the formation short string is described below.
      • Possible use case: Display the formation of a train on a track for a specific stop.
  2. Train-based – https://api.opentransportdata.swiss/formation/v2/formations_vehicle_based:
    • This service returns the formations per vehicle (i.e. per formation element) of the train.
    • Parameters:
      • The same as for formations_stop_based.
      • Operating day: The day for which the formation is to be queried. The date can be up to three days in the future.
    • Return values: a JSON data structure with:
      • the formation elements with details of each vehicle, the position of the vehicle in the formation, the stops where the vehicle stops along the journey, with details of the stop, and the track and sector where the vehicle stops at each stop.
      • This request does not provide a complete view of the train along the stops.
    • Possible use case: Tracking a specific car.
  3. Stop- and train-based – https://api.opentransportdata.swiss/formation/v2/formations_full
    • This service provides the formations for both stops and vehicles.
    • Parameters: same as for formations_stop_based and formations_vehicle_based.
    • Return values: a JSON data structure with the stops and formation elements as for the respective variants described above.
  4. Status info about the service – https://api.opentransportdata.swiss/formation/v2/health
    • This endpoint provides the status of the current operating state.
    • Parameters: none.
    • Return values: a JSON data structure with the current operating state of the service.

The query parameters

The following parameters are passed as query parameters after a ‘?’ in the URL (GET request):

Parameters Value description and example value
evu The EVU (Railway undertaking) for which the request is to be made. The following are currently supported: BLSP, SBBP, MBC, OeBB, RhB, SOB, THURBO, TPF, TRN, VDBB, ZB.
operationDate The date the train runs and for which you want to make the request. Example: 2024-09-18.
trainNumber The train number for which you wish to query the formation data. Example: 2806.

An example request would therefore be: https://api.opentransportdata.swiss/formation/v2/formations_stop_based?evu=BLSP&operationDate=2025-08-28&trainNumber=2806

The answer

We will not describe the full data model here, but instead refer to the following YAML:

Interpretation of the formation short string:

Basically, the structure of the string differs depending on whether a track has sectors and whether we know them.

In any case, the following applies to the construction:

Item Description
Sector Point („A“ … „Z“)
Status „-“ Vehicle closed
„>“ Vehicle with groups starting at this BP
„=“ Vehicle (partly) reserved for groups in transit
„%“ Vehicle open but not served (dining cars only)
Note: ‘closed’ can only occur on its own, the other characters can be combined
 [ Start of the vehicle group belonging to the train
Note: This makes it possible to distinguish between vehicles which are stabled or which are to be removed and those which belong to the moving train.
 ]

End of the vehicle group belonging to the train
Note: This makes it possible to distinguish between vehicles which are stabled or which are to be removed and those which belong to the moving train.
 (

no access to the neighbouring vehicle possible on this side of the vehicle
Note: The calculation is based on master data and assumptions. There is no guarantee that this information will always correspond to reality.
 )

no access to the neighbouring vehicle possible on this side of the vehicle
Note: The calculation is based on master data and assumptions. There is no guarantee that this information will always correspond to reality.
Vehicle type CI

Vehicle type from the perspective of customer information. This means:
– ‘1’ 1st class passenger coach
– ‘2’ passenger coaches 2nd class (also downgraded A/AB)
– ‘12’ passenger coaches 1st and 2nd class
– ‘CC’ couchette car
– ‘FA’ family coach
– ‘WL’ sleeping car
– ‘WR’ restaurant (bistro car, dining car, etc.)
– ‘W1’ combined dining car and 1st class seating car
– ‘W2’ combined dining car and 2nd class seating car
– ‘LK’ traction unit
– ‘D’ baggage car
– ‘F’ fictitious car
– ‘K’ Classless vehicle
– Parked coach ‘X’ Note: CUS converts the vehicle type obtained from FOS into a generic ‘AI type’.

The following variants are used:
1. Conversion of extra-long vehicles: Multiple units that deliver the source as a (super-long) vehicle rather than individual coaches can be configured by CUS into individual coaches. Not 1 vehicle (usually of type) then appears in the string „12“), but 2…n vehicles of type „1“, „2“, „12“ or „D“. The number is determined from the number of vehicles as perceived by the customer. Vehicles of this type which do not put first class right in the centre of the train are generally classified as classless vehicles of „K“ transformed.
2. Converting Individual Vehicles Based on Regular Expressions: All individual vehicles are converted into generic AI vehicles via prioritized regular expressions.
3. Conversion of individual vehicles based on the number of seats: If no regular expression from 2) matches, the type is determined on the basis of the number of 1st and 2nd class seats. If the vehicle does not have seats, the type „D“ assigned.

Note regarding “F”: On tracks with sectors, the front and/or rear delta between the train and stop edge length is filled with imaginary coaches.

Note regarding “X”: Stabled wagons influence how a train’s vehicles are allocated to the sectors, but they are not part of the train in question.
OrdNo. Serial number for the individual seat reservation displayed as such on the passenger coach (1…3-digit number)
Services List of vehicle-related offers. These include:
– „BHP“ Wheelchair spaces
– „BZ“ Business zone
– „FZ“ Family zone
– „KW“ Pram platform
– „NF“ Vehicle with low-floor access
– „VH“ Bicycle hooks/platform
– „VR“ Bike hooks/platform subject to reservation

What are the most important terms and concepts to know?

We use the following elements as part of our interface (without container elements):

  • StopPoint
    • A StopPoint is a stop along the timetable.
  • StopTime
    • Departure and arrival times.
  • Track
    • The track at the StopPoint.
  • FormationShortString
    • The short representation of the formation (as defined by CUS).
  • VehicleGoal
    • Which wagons stay together to which destination, as seen from one stop.
  • JourneyMetaInformation
    • Unique identification of the journey.
  • TrainMetaInformation
    • Descriptive properties of the train.
  • FormationMetaInformation
    • Details of the entire formation, e.g. the number of vehicles.
  • ScheduledStop
    • StopPoint, StopTime, Track, Details of the behaviour of the train at the stop (e.g. whether the train is stopping or passing through) and changes to the journey (e.g. delays in arrival).
  • VehicleIdentifier
    • Attributes that uniquely identify a vehicle, such as the european vehicle number (EVN). A special feature of this is that a vehicle can be part of an articulated train and therefore no separate EVN but only a ‘generated’ one. In this case, the ‘Parent-EVN‘ .
  • WheelchairSymbolProperties
  • AccessibilityProperties
    • Additional features that can be used to make it accessible to people with disabilities.
  • PictoProperties
    • Whether the various pictographies are displayed on a vehicle.
  • DirectTrolleyInformation
    • If the formation represents direct coaches.
  • VehicleRelation
    • This element allows the previous and subsequent journey in the given formation to be tracked. This can also be a direct coach journey.
  • VehicleProperties
    • Properties of a vehicle as part of a formation, i.e. a formation element, and from where and to where the coach is part of the formation.
  • FormationVehicleAtScheduledStop
    • The formation for each stop (for the vehicle_based request).
  • VehicleRelationship
    • The trip relationship, i.e. how the journey changes between two journeys (e.g. if there is a cancellation).
  • VehicleRelationshipDetails
    • The details of a journey relationship.

Restrictions

  1. The data is limited to railway undertakings (EVU)Who provide their formations via Swiss Federal Railways (SBB) and have consented to their data being published as Open Data.
  2. The service will only make all the data and the vehicle-based data available if all the sources have all the required data. This is particularly important considering that CUS only has data for today.
  3. The data comes from the SKI real-time system (CUS – CUstomer Information System – VerkehrsMittel VM) and the Formation Services (FOS) of SBB.