Skip to content
LoginRegister
DEENFRIT
Home
Open data platform mobility Switzerland
  2. Cookbook
  3. Formation Data

Formation Data

Status October 2024. You can find information on continuous adjustments in our Changelog.

Background

What is formation data?

Formation data is information about the wagons (and locomotives) of a train. They contain not only the position of the individual wagons in a train, but also their characteristics. For example, the formation data can be used to find out which wagon of a specific train (e.g. train number 1234) provides low-floor access, i.e. allows easy access for wheelchairs or pushchairs.

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 the Open Data platform offer this?

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

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

How do I access the data/interfaces?

Data

As formation data is constantly changing, we do not offer it as a data export, but only as an interface.

Interfaces

The formation data is provided here: https://opentransportdata.swiss/dataset/formations

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
    • You use the endpoint for this: formations_stop_based
    • What the service does:
      • Determine the formations per stop of a train’s journey.
    • What the service needs:
      • 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 +3 days (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 gives:
      • 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
    • To do this, use the endpoint: formations_vehicle_based
    • What the service does:
      • Determine the formations per vehicle (i.e. per formation element) of the train.
    • What the service needs:
      • The parameters are the same as for formations_stop_based
    • What the service gives:
      • 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
    • To do this, use the endpoint: formations_full
    • What the service does:
      • The formations can be issued both per stop and per vehicle.
    • What the service needs:
      • The parameters are the same as for formations_stop_based and formations_vehicle_based
    • What the service gives:
      • The stops AND the formation elements as in the respective variants described above.

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:

Sector Letter („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.
FzTypKI Vehicle 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.
OrdNr Ordinal number for the individual seat reservation which is displayed on the carriages for passengers (1…3-digit number)
Angebot Offer 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).

Technical description

Access to the API

A token is required to be able to use the API/interface. This token can be obtained via the Developer Portal.

The specific endpoints

The three endpoints described above can be accessed via the following URLs:

The parameters are as follows:

Parameter Value description and example value
evu The RU for which the enquiry is to be made. Currently permitted: BLSP, SBBP, MBC, OeBB, RhB, SOB, THURBO, TPF, TRN, VDBB, ZB
operationDate The date on which the train runs and for which you want to make the request. E.g. 2024-09-18
trainNumber The train number for which you want to query the formation data. E.g. 2806
includeOperationalStops Whether 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/formations_stop_based?evu=BLSP&operationDate=2024-09-18&trainNumber=2806&includeOperationalStops=false

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

[a swagger documentation may be available here in the future]

Restrictions

  • The interface exists as a beta as of October 2024 and is being continuously developed. This means that the data model can still change.