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
orREPAIR
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 namedclasz
. This is an artificial classification:- 0 flights
- 1 long distance high speed trains (e.g. TGV)
- 2 long distance inter city trains
- 3 long distance buses
- 4 long distance night trains
- 5 regional express trains
- 6 regional trains
- 7 metro trains
- 8 subway trains
- 9 trams
- 10 buses
- 11 ships/ferries
- 12 other (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 sufficientCANCELED_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.