Table of contents

Search on the page

Train Formation Service (Train Composition)

Brief Description

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

Our formation data can be used, for example, to find out which wagon of a specific train (with a given train number) provides low-floor access, i.e. allows easy access for wheelchairs or pushchairs.

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

Access the API:

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

Functional Description

Who is behind it?

The service is provided by the Customer Information Plus (SKI+) system tasks team on behalf of the Federal Office of Transport (FOT) in Switzerland.

We obtain the data on the formations from two systems:

  1. The Formation Service (FOS) is the SBB interface to which various railway undertakings (RUs) submit their formation data.
  2. The means of transport interface of the real-time system (CUS) of the Customer Information System (SKI), which manages the real-time data of all means of public transport.

While the FOS interface “only” provides the details of the formations, the CUS interface enriches the data with details such as the position of the wagons (sectors) on the track at the stops.

Why does our open data platform offer this?

Knowledge about the formation of a train can be used to inform users:

  • at which sector of a track of a railway station wheelchair access is possible (which is particularly important in the context of the Disability Discrimination Act BehiG)
  • in which carriages bicycle hooks are available
  • how many seats are generally available in a carriage
    • In combination with our occupancy forecast, the occupancy (train-wide) can even be displayed
  • which locomotive and wagon types run on which routes (e.g. for trainspotters, or for transport companies that combine their services with the railways)

Technical Description

Which services (interface endpoints) does the formation data interface offer?

The formation data interface supports the following request variants. The details of the requests are also documented via the OpenAPI interface:

  1. Stops based – https://api.opentransportdata.swiss/formation/v1/formations_stop_based
    • What the service does:
      • Determine the formations per stop of a train’s journey.
    • What the service needs as parameters:
      • The name of an RU: The list of authorised RUs is limited to those who have given their consent to the use of their formation data.
      • An operating day: The day for which the formation is to be queried. The date cannot be in the past. The date can only be today (due to the inclusion of real-time data from CUS).
      • The train number (also known as the means of transport number): The train for which you want to request the formation. This number can be obtained in various ways, including via our timetable data (in various data formats).
    • What the return service returns:
      • The stops of a train, with the details of the stops, the formation with which the train departs from the stops, and when, from which track, and with which locomotives/wagons stay together until where. The decisive factor here is that we specify the formation in a compact notation that has its origin in CUS!
      • This query does not contain all the details for each 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/v1/formations_vehicle_based
    • What the service does:
      • Determine the formations per vehicle (i.e. per formation element) of the train.
    • What the service needs as parameters:
      • The parameters are the same as for formations_stop_based
    • What the service returns:
      • The formation elements with the details of each vehicle, the position of the vehicle in the formation, as well as the stops at which the vehicle stops along the journey with the details of the stop, and the track and sector at which the vehicle stops at the respective stops.
      • This query does not include the overall view of the train along the stops.
    • Possible use case: Tracking a specific vehicle.
  3. Stops and train based – https://api.opentransportdata.swiss/formation/v1/formations_full
    • What the service does:
      • The formations can be issued both per stop and per vehicle.
    • What the service needs as parameters:
      • The parameters are the same as for formations_stop_based and formations_vehicle_based
    • What the service returns:
      • The stops AND the formation elements as in the respective variants described above.
  4. Status info about the service – https://api.opentransportdata.swiss/formation/v1/health
    • What the service does:
      • Sends the current operating status.
    • What the service needs as parameters:
      • Nothing, no parameters.
    • What the service returns:
      • The current operating status.

The query parameters

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

ParameterValue description and example value
evuThe RU for which the enquiry is to be made. Currently permitted: BLSP, SBBP, MBC, OeBB, RhB, SOB, THURBO, TPF, TRN, VDBB, ZB
operationDateThe date on which the train runs and for which you want to make the request. E.g. 2024-09-18
trainNumberThe train number for which you want to query the formation data. E.g. 2806
includeOperationalStopsWhether the operational stops (usually not relevant for customers!) should also be output. E.g. false

An example enquiry would therefore be: https://api.opentransportdata.swiss/formation/v1/formations_stop_based?evu=BLSP&operationDate=2025-04-22&trainNumber=2806&includeOperationalStops=false

The response

We will not describe the complete data model here, but instead refer to the following YAML: formations_yaml_change_file_ending_v0.6.1.yml.txt (file is a “.txt”, must be changed to “.yaml”).

Interpretation of the formation short string:

Basically, the structure of the string differs depending on whether a track has sectors or whether these are known to us.

In any case, the following applies to the structure:

ElementDescription
SectorLetter („A“ … „Z“)
Status„-“ Vehicle closed
„>“ Vehicle with groups boarding at this BP
„=“ Vehicle (partially) reserved for groups in transit
„%“ Vehicle open but unattended (only for dining cars)Note: “closed” can only appear alone; the other characters can be combined.
[Start of the vehicle group belonging to the train
Note: This allows vehicles that are parked or to be removed to be distinguished from vehicles belonging to the moving train.
]End of the vehicle group belonging to the train
Note: This allows vehicles that are parked or to be removed to be distinguished from vehicles belonging to the moving train.
(
No passage 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 corresponds to reality in every case.
)No passage 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 corresponds to reality in every case.
FzTypKIVehicle type from AI’s point of view. It means:
„1“ 1st class passenger coach
„2“ 2nd class passenger coaches (also declassified A/AB)
„12“ 1st and 2nd class passenger coaches
„CC“ couchette coach
„FA“ family car
„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“ luggage wagon
„F“ fictitious wagon
„K“ Classless vehicle
„X“ parked vehicleNote: CUS converts the vehicle type referred to from FOS into a generic “AI type”.

The following variants are used:
1. Conversion of overlong vehicles: Multiple units that deliver the source as a single (extra-long) vehicle rather than in wagons can be broken down into individual wagons by CUS. The string then does not contain 1 vehicle (usually of type “12”), but 2…n vehicles of type “1”, “2”, “12” or “D”. The number is based on the number of vehicles perceived by the customer. Vehicles of this type, which do not carry the first class in the centre of the train, are generally converted into classless vehicles of type “K”.
2. Conversion of individual vehicles based on regular expressions: All individual vehicles are converted into generic AI vehicles using prioritised regular expressions.
3. Conversion of individual vehicles due to the number of seats: If no regular expression from 2) matches, the type is determined based on the number of 1st and 2nd class seats. If the vehicle has no seats, it is assigned type “D”.

Note on “F”: On tracks with sectors, the delta between the length of the train and the stopping edge at the front and/or rear is filled with fictitious wagons.

Note on “X”: parked wagons influence the allocation of the vehicles in a train to the sectors, but are not part of the train in question.
OrdNrOrdinal number for the individual seat reservation which is displayed on the carriages for passengers (1…3-digit number)
AngebotOffer List of vehicle-related offers. These include:
“BHP” wheelchair spaces
“BZ” business zone
“FZ” family zone
“KW” pushchair platform
“NF” vehicle with low-floor access
“VH” bike hook/platform
“VR” bike hook/platform requiring 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
    • The departure and arrival time
  • Track
    • The track at the StopPoint
  • FormationShortString
    • The short representation of the formation (as defined by CUS)
  • VehicleGoal
    • Which carriages stay together until which destination as seen from a stop
  • JourneyMetaInformation
    • Clear identification of the journey
  • TrainMetaInformation
    • Descriptive properties of the train
  • FormationMetaInformation
    • Details of the entire formation, e.g. number of vehicles
  • ScheduledStop
    • StopPoint, StopTime, Track, details on how the train is handled at the stop (e.g. whether the train stops or passes through), as well as deviations in the journey (e.g. whether the train stops or passes through). Delays on arrival)
  • VehicleIdentifier
    • Attributes that uniquely identify a vehicle, such as the European vehicle number (EVN). A special feature here is that a vehicle can be part of an articulated train and therefore does not have its own EVN, but only a “generated” one. In this case, please refer to the “Parental EVN”.
  • WheelchairSymbolProperties
  • AccessibilityProperties
    • Other features that can be used in terms of disability-friendly presentation
  • PictoProperties
    • Whether the various pictographs are displayed on a vehicle
  • DirectTrolleyInformation
    • If the formation represents direct carriages
  • VehicleRelation
    • This element allows you to track the previous and subsequent movement of the given formation, which can also be a direct carriage movement
  • VehicleProperties
    • Characteristics of a vehicle as part of a formation, i.e. a formation element, and from where to where the vehicle is part of the formation
  • FormationVehicleAtScheduledStop
    • The representation of the formation per stop (for the vehicle_based request)
  • VehicleRelationship
    • The journey relationship, i.e. how the journey changes between two journeys (e.g. if there is a cancellation)
  • VehicleRelationshipDetails
    • The details of a travelling relationship.

Restrictions

  1. The data is limited to the railway undertakings (RUs) that provide their formations via the Swiss Federal Railways (SBB) and have consented to the publication of their data as open data.
  2. The service only provides all data and the vehicle-based data if all sources (see note 1) have all the required data. This is particularly important when you consider that CUS only has data for today + 3 days.
  3. Specifically, the data comes from the SKI real-time system (CUS – CUstomer (Information) System – VerkehrsMittel (VM)) and SBB’s Formation Services (FOS).