Connection

A connection is a journey from a coordinate/station to another coordinate/station. The core of the journey is the stop sequence. Other information (such as transports and trips) reference stops by their index in the stop sequence.

  • stops array of Stops

    The stop sequence including (real-time) event times and information about alighting and entering of services. This is the core of the journey. All other collections in the Connection reference stop indices.

  • transports array of Transports

    Information about the transports that are used with their corresponding stop range.

  • trips array of Trips

    Trip IDs for each trip that is used in the journey with their corresponding stop range.

  • attributes array of Attributes

    Attributes that are active within the corresponding stop range.

  • free_texts array of Free Texts

    Free text messages can be used by the operator to inform and guide users.

  • problems array of Problems

    Problems with the journey. This is empty for fresh journeys but can be populated when real-time information such as cancellations, etc. are processed.

Stop

The stops are the basic building block of the journey data structure. Everything else references stops by their index.

Note that there are four cases for exit and enter: when entering the first train, only enter is set. When exiting the last train, only exit is set. There may be walk segments before the first enter and after the last exit. For a direct interchange between two trains, enter and exit are set. For a walk between two stops, exit is set at the first stop and enter is set at the second stop. There may be more than one walk segments in between. For every stop where the train just stops, neither enter nor exit is set.

  • station see Station
  • arrival see Event Info
  • departure see Event Info
  • exit type boolean

    Indicates whether the passenger alights from the vehicle at this stop.

  • enter type boolean

    Indicates whether the passenger enters the vehicle at this stop.

Event Info

  • time type integer

    Real-time timestamp. See Times.

  • schedule_time type integer

    Schedule timestamp. See Times.

  • track type string

    The real-time track name.

  • schedule_track type string

    The schedule track name.

  • valid type bool

    If this flag is missing, the event is invalid. This is the case for the arrival event at the first stop and the departure event at the last stop.

  • reason

    The information source for the real-time timestamp. The system is conservative in the sense that it selects the maximum timestamp from propagation, forecast or schedule time if there is no IS or REPAIR timestamp given.

    • SCHEDULE: the real-time timestamp is the schedule time. No real-time information.
    • REPAIR: there are conflicting real-time information and this timestamp needed to be repaired such that basic properties of the timetable hold (i.e. timestamps need to correspond to the event order).
    • IS: the system received a real-time message that the event took place with this timestamp.
    • PROPAGATION: the timestamp was computed by propagating times (e.g. from earlier stops of the stop sequence of a trip)
    • FORECAST: the system received a message that forecasted the event time.

Transport

Note that this information is compressed: it can be the case that the transport spans multiple physical trips (with a interchange between - indicated by enter and exit) if the specified information (train number, etc.) does not change. But it can also be the case that there are multiple Transport items for one physical trip if the train number, category, provider, line ID or direction information change during the ride. Thus, generally there is a new Transport item when the referenced information changes.

  • range see Range
  • category_name type string

    The human readable category name.

  • category_id type integer

    The internal category ID.

  • clasz type integer

    The train class from 0 to 9. Since class is a reserved keyword in many programming languages, this entry is named clasz. This is an artificial classification:

    • 0: long distance high speed trains (e.g. TGV)
    • 1: long distance inter city trains
    • 2: long distance night trains
    • 3: regional express trains
    • 4: regional trains
    • 5: metro trains
    • 6: subway trains
    • 7: trams
    • 8: buses
    • 9: other (flights, ferries, taxis, etc.)
  • train_nr type integer

    The unique train if available.

  • line_id type string

    The line name/number.

  • name type string

    Complete official name. E.g. “TGV 123”

  • provider type string

    The name of the train operator company.

  • direction type string

    The direction of the train. This might be a station name but could also be a city name or something else.

Trip

In contrast to the Transports, there is one trip for each physical trip used in the journey. There might be multiple trips for one segment if there are multiple trains linked together.

  • range see Range

    The stop range where this trip is used.

  • id see Trip ID

    The trip ID. This can be used to uniquely identify the trip in other API requests.

  • debug type string

    A string of the form filename:123:456 specifying the filename and the line range (from 123 to 456) where the services is located in the input timetable. This is useful for debugging purposes.

Attribute

Attributes are used to convey further information about the service (e.g. WiFi availability, accessibility information, etc.). As for the Transports, attribute ranges may span multiple physical trips if the attribute applies to both trips.

  • range see Range

    The stop range where this attribute applies.

  • code type string

    A unique ID for the attribute.

  • text type string

    The display text for this attribute.

Free Text

Free texts are used to inform the user about real-time updates of any kind.

  • range see Range

    The stop range where this free text information applies.

  • code type integer

    A unique ID for the free text.

  • text type string

    The display text for this attribute.

  • type type string

    Type of the information.

Problem

When checking journeys with the revise module, it may find that the journey is not feasible anymore. This will be expressed by the problem annotations.

  • range see Range

    The stop where the problem appears.

  • type type enum

    The reason why the journey is not feasible anymore:

    • INTERCHANGE_TIME_VIOLATED: the interchange time between arrival and departure is not sufficient
    • CANCELED_TRAIN: a train in the journey was cancelled. This problem type is also set if the train does not service the stop (e.g. due to a rerouting) where the passenger wanted to enter/alight the train.

Range

The range type specifies two stop indices for which the given information applies.

  • from type integer

    The first index where the information applies.

  • to type integer

    The last index where the information applies.

Connection Example
{
  "stops": [
    {
      "station": {
        "id": "8591379",
        "name": "Zürich, Stampfenbachplatz",
        "pos": {
          "lat": 47.380292,
          "lng": 8.542776
        }
      },
      "arrival": {
        "track": "",
        "schedule_track": ""
      },
      "departure": {
        "time": 1586006460,
        "schedule_time": 1586006460,
        "track": "",
        "schedule_track": "",
        "valid": true
      },
      "enter": true
    },
    {
      "station": {
        "id": "8587349",
        "name": "Zürich, Bahnhofquai/HB",
        "pos": {
          "lat": 47.37756,
          "lng": 8.541741
        }
      },
      "arrival": {
        "time": 1586006580,
        "schedule_time": 1586006580,
        "track": "",
        "schedule_track": "",
        "valid": true
      },
      "departure": {
        "time": 1586006580,
        "schedule_time": 1586006580,
        "track": "",
        "schedule_track": "",
        "valid": true
      },
      "exit": true
    },
    {
      "station": {
        "id": "8503000",
        "name": "Zürich HB",
        "pos": {
          "lat": 47.378177,
          "lng": 8.540212
        }
      },
      "arrival": {
        "time": 1586007000,
        "schedule_time": 1586007000,
        "track": "",
        "schedule_track": "",
        "valid": true
      },
      "departure": {
        "time": 1586007000,
        "schedule_time": 1586007000,
        "track": "32",
        "schedule_track": "32",
        "valid": true
      },
      "enter": true
    },
    {
      "station": {
        "id": "8500218",
        "name": "Olten",
        "pos": {
          "lat": 47.351935,
          "lng": 7.907699
        }
      },
      "arrival": {
        "time": 1586008800,
        "schedule_time": 1586008800,
        "track": "3",
        "schedule_track": "3",
        "valid": true
      },
      "departure": {
        "track": "",
        "schedule_track": ""
      },
      "exit": true
    }
  ],
  "transports": [
    {
      "move_type": "Transport",
      "move": {
        "range": {
          "from": 0,
          "to": 1
        },
        "category_name": "T",
        "category_id": 2,
        "clasz": 7,
        "train_nr": 12083,
        "line_id": "14",
        "name": "T 14",
        "provider": "Verkehrsbetriebe Zürich INFO+",
        "direction": "Zürich, Triemli                                   "
      }
    },
    {
      "move_type": "Walk",
      "move": {
        "range": {
          "from": 1,
          "to": 2
        },
        "mumo_id": -1,
        "mumo_type": ""
      }
    },
    {
      "move_type": "Transport",
      "move": {
        "range": {
          "from": 2,
          "to": 3
        },
        "category_name": "IC",
        "category_id": 23,
        "clasz": 1,
        "train_nr": 1526,
        "line_id": "5",
        "name": "IC 5",
        "provider": "Schweizerische Bundesbahnen SBB",
        "direction": "Lausanne"
      }
    }
  ],
  "trips": [
    {
      "range": {
        "from": 0,
        "to": 1
      },
      "id": {
        "station_id": "8591354",
        "train_nr": 12083,
        "time": 1586005440,
        "target_station_id": "8503610",
        "target_time": 1586007660,
        "line_id": "14"
      },
      "debug": "FPLAN:1814564:1814599"
    },
    {
      "range": {
        "from": 2,
        "to": 3
      },
      "id": {
        "station_id": "8506302",
        "train_nr": 1526,
        "time": 1586002020,
        "target_station_id": "8501120",
        "target_time": 1586015100,
        "line_id": "5"
      },
      "debug": "FPLAN:86300:86327"
    }
  ],
  "attributes": [
    {
      "range": {
        "from": 2,
        "to": 3
      },
      "code": "Businesszone in 1. Klasse",
      "text": "BZ"
    },
    {
      "range": {
        "from": 2,
        "to": 3
      },
      "code": "Ruhezone in 1. Klasse",
      "text": "RZ"
    }
  ],
  "free_texts": [],
  "problems": []
}